Pog Scripting Language SDK Documentation
V0.91 Beta - January 2002
This documentation is the primary source of information on the Pog scripting language and tools used by the Flux engine and the game Independence War 2: Edge Of Chaos. If you are new to Pog you should read the introduction.

For language specifics refer to the language reference.

We shall refer to the game Independence War 2: Edge Of Chaos as I-War 2 throughout this document.

Note: This document is not a tutorial for the Pog language, or the ANSI C language on which it is based. It assumes that you have at least a basic knowledge of programming in a C-like programming language.

Important: You must read and agree to the License Agreement before using this document, and any of the contents of the Pog SDK.

Accuracy: While we have made every effort to ensure the information in this SDK is accurate, we cannot guarantee that the SDK and its documentation is completely accurate and free of errors. For definitive information on a particular pog function please consult the header files supplied with the SDK.

Support: This is a beta release of the SDK and documentation, and is not supported by Particle Systems or Infogrames. Pog Scripting queries may be placed on the US Infogrames Independence War Forum.

Table of contents

  • License Agreement
  • Introduction
  • Language Reference
  • Package Reference
  • Developing Scripts
Copyright © 1999-2002 Particle Systems Ltd. All rights reserved.


Pog Scripting SDK License Agreement
You must read and agree to this license agreement before using the Pog Scripting SDK.

INDEPENDENCE WAR 2: EDGE OF CHAOS POG SCRIPT SDK LICENSE AGREEMENT

The contents of the Independence War 2: Edge Of Chaos "IW2:EOC" Pog Scripting SDK "SDK" are supplied 'as-is', and no warranty is given as to their suitability or fitness for any purpose.

PARTICLE SYSTEMS and INFOGRAMES accept no responsibility for any loss or damage however caused by use of the SDK. All responsibility for use and consequences of the use of the SDK rest solely with the user.

The User may freely distribute in a non-commercial manner the SDK providing that:

  1. The SDK is not sold, bartered, or distributed with any other product for which any charge is made (other than incidental charges for time spent on-line), but rather must be distributed free of charge.
  2. The SDK contents including this license agreement are distributed together in their entirety and in an unmodified form.

RULES GOVERNING MODS AND MOD EDITORS FOR INDEPENDENCE WAR 2: EDGE OF CHAOS

'MODS' are data that modify, add to, or substitute for data in the IW2:EOC Software, thus modifying, adding to, or replacing content provided by PARTICLE SYSTEMS in the Software.

'MOD EDITORS' are programs that create data to modify, add to, or substitute for data in the IW2:EOC Software, thus modifying, adding to, or replacing data provided by PARTICLE SYSTEMS in the Software.

MODS / MOD EDITORS may be permitted by PARTICLE SYSTEMS and INFOGRAMES at their sole discretion, on the following conditions:

  1. MODS / MOD EDITORS must work only with the retail version of the Software, and may not work with any demo or OEM versions of the Software.
  2. MODS / MOD EDITORS may not modify any COM, EXE, DLL or
    other executable files.
  3. MODS / MOD EDITORS must not contain any illegal, scandalous, illicit, defamatory, libelous, or
    objectionable material (as may be determined by PARTICLE SYSTEMS and INFOGRAMES in their sole
    discretion), or any material that infringes any trademarks, copyrights, protected works, publicity,
    proprietary, or other rights of any third party or of PARTICLE SYSTEMS and INFOGRAMES.
  4. MODS must identify in every description file, on-line description, read-me, and in comments in the MOD data:
  1. The name, address, and e-mail address of the MODS creators, and
  2. The following disclaimer: "THIS MOD IS NOT MADE, DISTRIBUTED, OR SUPPORTED BY INFOGRAMES OR PARTICLE SYSTEMS LTD. ELEMENTS TM & (C) INFOGRAMES AND PARTICLE SYSTEMS LTD.
  5. MOD EDITORS must identify in every description file, on-line description, read-me, and in comments in
    the MOD EDITOR data:
  1. The name, address, and e-mail address of the MOD EDITOR creators, and
  2. he following disclaimer: "THIS MOD EDITOR IS NOT MADE, DISTRIBUTED, OR SUPPORTED BY INFOGRAMES OR PARTICLE SYSTEMS LTD. ELEMENTS TM & (C) INFOGRAMES AND PARTICLE SYSTEMS LTD.
  6. MODS / MOD EDITORS may not be sold, bartered, or distributed with any other product for which any charge is made (other than incidental charges for time spent on-line), but rather must be distributed free of charge.
  7. By distributing or permitting the distribution of any MODS / MOD EDITORS, all creators or owners of any trademark, copyright, or other right, title or interest therein grant to PARTICLE SYSTEMS and INFOGRAMES an irrevocable, perpetual, royalty-free, sublicensable right to use and distribute the MOD / MOD EDITOR by any means (whether now known or hereafter invented), and to create and distribute by any means (whether now known or hereafter invented) derivative works thereof, and to charge for the distribution of such MOD / MOD EDITOR or such derivative work, with no obligation to account to any creators or owners of the MOD / MOD EDITOR in any manner.

Copyright © 1999-2002 Particle Systems Ltd. All rights reserved.


Introduction

Pog is the Flux engine's built-in scripting language. It is intended for authoring game rules, object behaviours, scenarios and other forms of gameplay code. Pog is based on the ANSI C language and borrows many elements from it. It also provides additional features which are intended to facilitate the writing of gameplay code.

This section is a brief introduction to the concepts of Pog scripting. Please see the reference section for detailed information.

  • Scripts
  • Packages
  • Compiling
Copyright © 1999-2002 Particle Systems Ltd. All rights reserved.


Pog Scripts

A script file is a single text file written in the Pog scripting language. It will consist of a group of functions. Normally these functions are related to another, though this doesn't have to be the case.

A script might define the behaviour of a game object, such as a spaceship, or it could be a collection of utilities for use in other scripts, or even the entire plot structure of a game.

Functions in scripts can be provided for use by other scripts. This means that complex scripts can be created from simpler component scripts, which makes the Pog scripting language very powerful.

Each Pog script follows a standard format, and must be compiled into a package before use.

A Pog script has the extension .pog, e.g. My_Script.pog


Pog Packages

Pog scripts are compiled into small binary files known as packages. These compiled packages are very small, which makes them ideal for distribution.

A Pog package resides in the <game folder>resource\packages\ folder of the game, and has the extension .pkg, e.g. myscript.pkg

Each package may contain one or more individual Pog functions, any of which can be made available for use by other packages. In this way the Pog language can be extended with user-created functions and packages.

Normally a package will contain related functions, though this is not always the case.


Compiling Pog Scripts into Packages

Pog scripts are compiled into packages using the Pog Compiler. The compiler is a command line program that tokenises the Pog scripts and outputs a binary package file.

During the compilation process the Pog compiler checks the script for syntax other errors, and will only output a binary package if no errors are found.

See the Pog Compiler section for details of how to install and use the Pog compiler.

Introduction


Language Reference

This section of the manual provides formal information about the Pog language. It describes the aspects of the language which differ from or extend ANSI C, as well as indicating those aspects which are similar to or the same as their C counterparts.

Fundamentals

  • Differences from C / C++
  • Structure of a Pog Script

Basic language features

  • Fundamental data types
  • Literal values
  • Enumerators
  • Expressions, Operators and Precedence
  • Functions, prototypes and function calls
  • Conditionals
  • Loops
  • Globals
  • Comments

Advanced language features

  • Multitasking
  • Handle types
  • Resource URLs
  • Flux Classes
  • Debug and Atomic Blocks
  • Schedules
  • Header Files
  • Configuration INI Files
  • Text CSV files
  • Object Properties and Death Scripts
  • States

Formal information

  • List of reserved words

Copyright © 1999 - 2002 Particle Systems Ltd. All rights reserved.


Differences from C / C++

Pog shares many features with C, but is not identical. Much of the syntax should be familiar from ANSI C , but Several C features have been removed, and Pog has additions tailored for its task.

Unsupported C / C++ Features

The following features of C are not supported in Pog:

  • Pointers
  • Structures
  • Unions
  • Arrays

Differences

The following features operate differently from C:

Variable Declaration
Unlike C, variable declarations cannot be used at the start of any new block – variables can only be declared immediately at the start of a function definition.

Strings
The C data type char does not exist in Pog, instead the data type string represents a string of zero or more characters. See Fundamental Data Types for more information.


Pog Script Structure

Each separate Pog script file defines a Pog package that can contain one or more functions.

A Pog script filename has the extension .Pog, e.g. My_Script.Pog

The structure of a Pog script is common for all Pog scripts. Here's a sample Pog script for a package called iExample.

// Example Pog package

// Package name
package iExample;

// Imports - the other packages we are using in this script.
uses Debug;

// Exports - Functions in this package that other scripts can use.
provides Main;

// Enumerators (optional) - Any enumerators for the script defined here.
enum eSample
{
    SE_First_Enum,
    SE_Second_Enum,
    SE_Final_Enum = 100
};

// Prototypes - Functions defined for use in this package.
prototype Main();

// Code starts here

Main()
{
    int count;

    for ( count = 0 ; count < 10 ; ++count )
    {
        debug Debug.PrintString("This is an example\n");
    }
}

// END OF FILE

Package Name

package iExample;

The script starts with the package name. This is the filename the script's package will use when it's compiled, with the .pgk extension added, e.g. iexample.pkg, and will also be the prefix for any exported functions if they are used in other scripts, e.g. iExample.Main()

The package name must be unique.

Imports

uses iDebug;

Following the package name is the uses section. This is a comma separated list of other packages that are used in the script. It's essential that you include all the packages your script uses, otherwise the script will fail to compile.

In our example the script uses one package only - the Debug package.

Exports

provides Main;

The Pog script makes available its functions for use by other scripts in the provides section. At least one function in each package must be exported, otherwise there will be no way to access any functions in your package.

Any exported functions will also need to be included in the packages header file, if you wish to compile other scripts that use those functions. See the Header Files section for more information.

Note that you don't specify any of the function's arguments when you export it.

Enumerators

enum eSample
{
    SE_First_Enum,
    SE_Second_Enum,
    SE_Final_Enum = 100
};

Optionally, following the provides section, Any enumerators may be defined. See the Enumerators section for more details.

Prototypes

prototype Main();

A function prototype is similar to a C function prototype – it informs the compiler of the name, type and arguments of a function before the function is properly defined. It is good practice to prototype every function in a package, as this provides the package with an easy to find quick reference list to all the functions in the package.

If you wish to reference a non-prototyped function in another function of your script you will need to make sure the function definition is defined before the function is called in the script. Otherwise the script will generate an error when compiled. This is another good reason to prototype all of your functions.

Code Block

The final section of the script is the code block where the script's functions are defined. In our example we have one function containing a simple for-next loop which prints the same debug message ten times.

See the Functions, prototypes and function calls section for details of function structure.


Fundamental Data Types

This page describes the fundamental data types supported by Pog. For information on more complex built-in types, refer to the advanced types and handle types pages.

    Numerical types

    int
    An int is a 32-bit signed integer type. It can represent positive and negative whole numbers and the number zero.

    float
    A float is a 32-bit IEEE floating-point type. It can represent positive and negative fractional numbers and zero. A float can store approximately 6 or 7 significant figures. Larger numbers are therefore represented with less precision than small numbers.

    Boolean type

    bool
    The type bool represents one of the Boolean values true and false. It cannot store any other value.

    String type

    string
    The type string represents a set of zero or more characters. Note: Strings are manipulated using the String package.

    Type conversions

    Pog provides the following type conversions automatically:

    Source type | Destination type | Notes
int | float | Converting an int to a float may result in a loss of accuracy.
int | bool | The result will have the value true if the integer is nonzero, or false if it is zero.
float | int | Converting a float to an int will truncate the value, i.e. remove any fractional part to obtain a whole number.
float | bool | The result will have the value true if the float is nonzero, or false if it is exactly zero.
bool | int | The result will have the value 1 for true or 0 for false.
bool | float | The result will have the value 1.0 for true or 0.0 for false.


Literal Values

This page describes the literal value types supported by Pog.

Overview

A literal value is a constant whose value is known at compile time. For example, the value 10 is an integer literal, but the name of an integer variable is not since its value will be determined at run-time by the assignments made to it.

Literals are distinguished from constants by having no name. Constants are names for literals that may be re-used.

Numeric literals

A decimal integer literal has one of the following forms:
0
dddddd
Where each 'd' is a decimal digit, with the first one nonzero.

For example, 0, 123 and 45600789 are all decimal integer literals. 01 and 00345345 are not.

The literal's value is is its usual value as a decimal number. It has the type int.

A hexadecimal integer literal has one of the following forms:
0xhhh
0Xhhh
Where each 'h' is a hexadecimal digit, which is either a decimal digit or one of the letters A-F. Hexadecimal digits are not case sensitive.

For example, 0xabcd and 0x12EF are hexadecimal integer literals. abcd and 00Xab are not.

The literal's value is its usual value as a hexadecimal (base 16) number. It has the type int.

Hexadecimal numbers are useful for writing sets of flags, since encoding individual binary bits is easy in hexadecimal.

A floating-point literal has one of the forms:
nnn.nnn
nnn.
.nnn
Where each 'n' is a decimal digit.

It may optionally have an exponent suffix which has one of the forms:
e nnn
e -nnn
Where 'e' is the letter e, in upper or lower case, and each 'n' is a decimal digit.

For example, 1.0, .1 and 13.0e-2 are all floating point literals. E10 and 123 are not.

The literal's value is the usual decimal value of the first part, multiplied by 10 to the power of the exponent part, if it is present. It has the type float.

Boolean literals

There are only two boolean literals - the named values true and false. They have the type bool.

Handle literals

There is only one handle literal, the named value none. It does not have a true type, but it is compatible with any handle type.

String literals

String literals have one of the following forms:
""
"ccccccc"
Where each 'c' is an ASCII character other than '"', or an escape sequence.

The string literal is therefore simply a sequence of characters enclosed in double- quotation marks. Within the quotation marks certain characters may have their usual meanings changed using the escape character '\'. This allows non-printing characters to be embedded in strings, for example. The compiler converts escape sequences to the appropriate characters when it parses the string literal.

The following table lists the character escape sequences supported in Pog string literals:
Sequence | Meaning
\n | New line
\t | Horizontal tab
\v | Vertical tab
\b | Backspace
\r | Carriage return
\f | Form feed
\a | Bell
\\ | Literal backslash
\' | Literal single-quote mark
\? | Literal question mark

Note:

Pog does not support any numeric escape sequences.


Enumerators

Overview

An enumerator is a way of labelling an integer constant so it can be referred to by label rather than value. The scope of Enumerators encompasses the script in which it was defined, unless the eumerator is exported in a header file for use by other scripts.

Defining an Enumerator

enum eSampleEnum
{
    SE_First_Enum,
    SE_Second_Enum,
    SE_Final_Enum = 100
};

The above sample enumeration shows how an enumeration is defined.

The enumeration must be defined in a Pog Script immediately after the script's exports section and before the script's prototypes section. See the Pog Script Structure for more information on this.

Additionally if the enumeration is be used by other Pog scripts the enumerator must be also defined in the script's header file. See the Header Files section for details.

Enumerator name

enum eSampleEnum

An enumerator must have a unique identifier. By convention this begins with a lowecase 'e', as in the example above.

Enumerator Block

{
    SE_First_Enum,
    SE_Second_Enum,
    SE_Final_Enum = 100
};

Following the enumeration name is the enumerator block. This defines the values of the enumerated types in the enumerator.

The block is a comma separated list of names. By convention the names begin with a short identifier that in some way links them to the enumerator name. Our example uses 'SE_' for 'Sample Enum'.

Note:
There is no comma after the final name, and that the block ends with a semi-colon ';'

Assigning Values
Each name can be automatically or manually assigned an integer value. If a value isn't assigned then the first name in the list is assigned the value '0', the second '1', etc.

To assign a value manually use an equal sign, just like a normal assignment. e.g.

SE_Final_Enum = 100


Expressions, Operators and Precedence

Overview

Expressions are pieces of Pog code which have an intrinsic value attached to them. They may perform work as a side-effect. The chain of expression rules defines the precedence of operators, which follow ANSI C precedence conventions. Not all C operators are implemented in Pog.

The following tables describe the operators supported by Pog, and their precedence.

Mathematical Operators

Operation | Symbol | Notes
Addition | + |
Subtraction | - |
Multiplication | * |
Division | / |
Modulo (remainder) | % | Returns the integer remainder after an integer division. i.e. 5%3 returns 2

Comparison Operators

Operation | Symbol | Notes
Equality | == |
Inequality | != |
Not | ! |
Less Than | < |
Less Than or Equal | <= |
Greater Than | > |
Greater Than or Equal | >= |

Logical Operators

Operation | Symbol | Notes
And | && |
Or | || |
Not | ! |

Bitwise Operators

Operation | Symbol | Notes
Bitwise And | & | 4 & 8 will yield 0 4 & 7 will yield 4
Bitwise Or | | | 4 & 8 will yield 12 4 & 7 will yield 7
Bitwise Exclusive Or | ^ | 4 ^ 8 will yield 12 4 ^ 7 will yield 3 Adds the bits that are only on in one of the two numbers
Bitwise Not | ~ |

Assignment Operators

Operation | Symbol | Notes
Assignment | = | x = y will set x to the value of y
Additive Assignment | += | x += y will set x to the value of x + y
Subtractive Assignment | -= | x -= y will set x to the value of x - y
Multiplicative Assignment | *= | x *= y will set x to the value of x * y
Divisive Assignment | /= | x /=y will set x to the value of x / y
Remainder assignment | %= | x %=y will set x to the value of x % y
Bitwise And assignment | &= |
Bitwise Or assignment | |= |
Bitwise Xor assignment | ^= |
Bitwise Not assignment | ~= |
Auto Increment | ++ | x++ will increment x by 1 with the value returned being that of x ++x will increment x by 1 with the value returned being that of x+1
Auto Decrement | -- | As above

Order Of Precedence

Highest Precedence |  |
++ | Post-increment | Left to right
-- | Post-decrement | Left to right
( ) | Function call | Left to right
[ ] | Array element | Left to right
++ | Pre-increment | Right to left
-- | Pre-decrement | Right to left
! | Logical NOT | Right to left
~ | Bitwise NOT | Right to left
- | Unary minus | Right to left
+ | Unary plus | Right to left
* | Multiply | Left to right
/ | Divide | Left to right
% | Remainder | Left to right
+ | Add | Left to right
- | Subtract | Left to right
<< | Left shift | Left to right
>> | Right shift | Left to right
< | Less than | Left to right
<= | Less than or equal to | Left to right
> | Greater than | Left to right
>= | Greater than or equal to | Left to right
== | Equal | Left to right
!= | Not equal | Left to right
& | Bitwise AND | Left to right
^ | Bitwise exclusive OR | Left to right
| | Bitwise OR | Left to right
&& | Logical AND | Left to right
|| | Logical OR | Left to right
? : | Conditional | Right to left
= | Assignment | Right to left
*=, /=,%=, +=, -=, &=, ^=, |= | Compound assignment | Right to Left
, | Comma | Left to right
Lowest Precedence |  |


Functions, Prototypes and Function Calls

Overview

Like C, Pog scripts are built up of functions. Functions can be exported from a script for use in another script, allowing the Pog language to be extended via scripted packages.

All variables defined in a function are local to that function, and cannot be accessed outside that function, except via a return statement.

Prototyping a Function

To make full use of a function in a script, you must prototype it first. This informs the compiler of the name, type and arguments of a function before the function is properly defined.

The prototype definition should be placed in the Pog script between the exports / enumerators section, and the script code block. See Pog Script Structure for details of where prototypes are defined.

The prototype takes the same form as the function header (detailed below), with the keyword prototype at the beginning. e.g:
prototype iExample.PrintHello( int number_of_times );

Defining a Function

A function consists of a header and a code block. The header contains the function definition, including the function name and its parameters, while the code block contains the actual code executed when the function is called.

Function Header

A function header takes the following form:
{ prototype } { task / return_type } { package_name }.identifier ( { formal_argument_list } )

An example:
int iExample.PrintHello( int number_of_times );

prototype
Used for prototyping a function.

task
This parameter is used to define multitasking functions. See Multitasking for more details. Task functions cannot return a value, as they return their task handle instead.

return_type
Non task functions can return a value, and their return type, i.e. bool, int, float, etc. must be specifed here if they do.

package_name
This is the name of the package. If the function being defined / used is located in the current script package, this parameter can be omitted.

identifier
This is the function name. By convention exported functions use upper and lower case names with no underscores, while non-exported functions use lower case names with underscores.

Example of exported function name
PrintHello()

Example of non-exported Function name.
print_hello()

formal_argument_list
This contains the comma separated list any parameters for the function. Not every function requires parameters. Some Any parameters defined here do not have to be defined in the function code block. The type and name of each parameter must be specified.

Example Parameters:
int count, float time, string name

Function Code Block

The function code block defines the code for the function.

Declaring Variables
Any variables used in the function must be declared at the start of the code block e.g:

my_function()
{
    int count = 1;

    Debug.PrintString( "Hello\n");
    Debug.PrintInt( count );
}

Returning Values
Non task functions can return a value. The value can be a variable, constant, expression, enumeration, or a handle. To return a value use the return statement. e.g.

return count;

Functions that return a value must specify the return value type in their prototype and function headers, e.g.:

prototype int my_function();
int my_function()
{
    count = 1
    return count;
}

Exporting Functions

To use a function in another script you must export it by placing its function name in the provides section of the Pog script, and also provide its definition in the script's header file. See Pog Script Structure and Header Files for details.

Calling functions

Task Functions
Task functions are a special case and must be called using the start command. See Multitasking for details.

Local Functions
To call a function in the script where it is defined, simply use the function name without the package name prefix. e.g.:

my_function();

Imported Functions
To use a function from a native code package or a different script package you must specify the package name of the function as well as the function name. Note that you must also specify any packages whose functions you wish to use in the uses section of the Pog script. See Pog Script Structure for details.

Example of an imported function call:

iExample.ImportedFunction();


Conditionals

Overview

Pog supports the standard ANSI C Conditionals:

  • if
  • else
  • switch


Loops

Overview

Pog supports the standard ANSI C loops:

  • For
  • Do / While
  • While

Pog also supports the standard ANSI C Loop Jump statements:

  • break
  • continue

Additionally Pog supports schedules, a timed loop for multitasking. See the schedules section for details.


Global Variables

Overview

Variables in Pog have limited scope - they cannot be used by other functions unless they are passed as parameters, or returned by a function.

To allow scripts more flexible access to variables in other scripts Pog supports global variables via the Global package.

Global variables are also saved out in I-War 2 save games, and so are ideal for keeping track of data you wish saved out.

See the Global package reference for more information.


Comments

Overview

Pog supports the standard C++ comment styles for single line comments and comment blocks, using //, /* and */

Note that INI and CSV files use the semicolon ; to comment out individual lines, and do not support multi-line comments.

// This is a single line comment
/* This is a multi line comment
    Debug.PrintString( "This code commented out" );
*/


Multitasking

This page describes Pog's ability to perform multiple tasks simultaneously. It explains how to write tasks, how to start new tasks running, and how to manipulate tasks which are running.

Overview

A task is an isolated context for executing Pog code. Tasks are unlike typical operating-system threads 1 in that they do not share the same address space 2. All tasks are protected from each other so that a task cannot manipulate the variables in another task. This is not the case with threads. Tasks do in a sense share a global address space - they are all running in the same game environment, and have shared access to the game objects and data.

All Pog code executing in the game is executing as a task, and the script engine allocates execution time to each task in turn. Flux provides the facility to start script functions as tasks (using FcScriptEngine::StartTask) or as function calls (using FcScriptEngine::CallFunction). Almost all gameplay code executes as tasks, since it executes while the game is running - calling a function while the game is running forces the entire game to wait for the function to finish, which is not usually the desired behaviour.

Task functions

A task is executed by starting a task function. This is a normal Pog function declared with the task keyword. Task functions may not have return values, since the execution of the task may take some time and the return value would have to be immediately available for the calling code to store. For example:

// This is a normal function prototype
prototype int normal_function( int parameter );

// This is a task function prototype
prototype task task_function( int parameter );

Note:
The task keyword in front of the task function is not a return value, it is a special declaration syntax to mark this function as a task function.

There are no other restrictions on task functions. They are in all other respects identical to normal functions.

Important:
A task function is not the same thing as a task. The task is the flow of program execution, and the task function is the program which directs the flow. Several tasks may start the same task function, but they are all different tasks. As an analogy, the task function is like a road, and the task like a car - the road guides the car, and the car represents progress along the road. Many cars can drive on the same road, and a car can leave one road and drive on another. This is like having a task function call other functions.

Starting a task

Normal functions are executed by calling them. This uses the normal C function call syntax whereby a function name followed by parameters in parentheses is a call expression whose type is the return type of the function.

Tasks are executed by starting a task function. This uses the same syntax, but the name of the function is preceded by the keyword start. This forms a start expression whose type is htask. The value of the function start expression is the handle to the task which has been started. The code which starts the task may store this handle in a variable and use it to manipulate the task via the API in the Task package.

Calling task functions or starting normal functions is not possible. The execution type must match the function type. This prevents code which is intended to be executed atomically 3 from being executed as a task, and vice-versa.

For example, a task function may include an infinite loop which waits for events to be signalled by the game. If the function were called atomically this loop would never receive events (time would not pass in the game while the loop executed) and the loop would not terminate. This would cause the task which had called the function to lock up.

The following example shows a task being started:

package TaskTest;

uses Debug;

provides Main;

// This task function prints the numbers from 1 to n
// to the log.
task log_n_numbers( int n )
{
    int i;

    for ( i = 1; i < n; ++i )
        Debug.PrintInt( i );
}

// This function starts three different print tasks to
// print different lists of numbers.
Main()
{
    start log_n_numbers( 10 );
    start log_n_numbers( 20 );
    start log_n_numbers( 30 );
}

Running the Main function in the example will start three tasks using the task function log_n_numbers. If you compile and run this package, the debug log file will contain the numbers 1 to 10, 1 to 20, and 1 to 30. The number sequences will probably be interleaved with other because the tasks are all running at the same time and do not attempt to synchronise their output.

Task handles

In the Flux engine, Pog tasks are represented as instances of the C++ class FcScriptTask. As described in the handle types section, this means that Pog code may use handles to access and manipulate tasks. Pog provides the following built-in type to represent tasks:

handle htask : hobject;

When a task is started from within Pog code, the handle to the task is provided automatically and appears to be a return value (although it is not really a return value - task functions have no return value.)

If you wish to access and manipulate the task after it has been created, you can store the task handle in a variable using an assignment in the usual way.

The current task

The Task package provides a function - Task.Current - for returning the handle of the current task. This function can always be used to obtain a handle for, and therefore control, the task currently executing a given piece of code.

Halting a task

A task which has finished execution is said to be halted. When a task is halted, the engine destroys the C++ object which represents the task. This means a halted task may never restart.

Tasks halt automatically when the flow of execution returns from the task function which was started to create the task. Tasks may be halted explicitly, if their handle is known, using the function Task.Halt. The current task may be halted in this manner if desired.

When a task halts, its child tasks (tasks which were started by that task) are also halted. If you need a child task to outlive its parent, then that task must be detached and made a new top level task, using the function Task.Detach.

1 Threads are strands of program execution. Multiple threads may execute simultaneously within a program, with each thread having access to all the code and data in the program.

2 Address spaces are the environments in which code is executed. The address space contains all the data which the executing code may access, or address.

3 Atomic execution is when a function is called as single operation. The function executes as soon as it is called, and control does not return to the point of call until the function has finished executing. This is the normal type of function execution.


Handle Types

This page describes the concept of handle types in Pog. Handle types allow script code to manipulate native objects which exist in the game engine.

If you are unfamiliar with C++ classes and class hierarchies, please read the overview of C++ classes and derived class relationships in this section before continuing.

Overview

A handle type is a means of referring to a C++ object. It is not the same thing as the object - it is simply a reference to it. Many packages provide facilities for manipulating C++ objects by exporting a handle type and functions which take parameters of that handle type.

Handle types are organised in a hierarchy which parallels the game engine's C++ class hierarchy. This allows handle types to take advantage of kind-of relationships in the class hierarchy in a safe way.

Base handle type

hobject
Pog provides a built-in handle type which is a handle to FcObject. Any Flux object may be referenced with this handle type, since FcObject is the base class of all Flux objects. However, the range of operations which may be performed on an instance of FcObject is comparitively small, since it doesn't really represent anything in the game world.

Handle type values

Handle types may store two kinds of value. The handle may refer to a C++ object, in which case its value is 'reference to that object'. This kind of value is opaque to script code i.e. it is impossible to print it or look at it. If the handle refers to no object, its value is the constant handle value none. This value may be assigned to any variable of a handle type to make that variable refer to no object.

Note: The value of a handle referring to an object is implemented as the object's 32-bit ID number as referred to in the C++ code. This number is unique and will never be reused by another object.

Defining handle types

Handle types are defined with the following syntax:
handle hderived : hbase;

This definition must be placed at file-scope, i.e. outside any function code.

It defines the handle type hderived as derived from the already- existing handle type hbase. This means that the C++ classes to which these handle types refer are derived from each other in the same way.

Note: This definition will usually be placed in the header file for a package which exports native code functions for working with objects which are instances of a particular C++ class. It is unlikely that pure script code will need to define handle types.

Type-conversions

As with the fundamental types Pog provides certain automatic type conversions between handle types, and also conversions between handle types and certain built-in types. In the following table, hbase represents a base handle type, and hderived represents a type derived from it.

Source type | Destination type | Notes
Any handle type | bool | The result will have the value false if the handle is equal to none or the value true if the handle refers to an object.
hderived | hbase | Any handle type may be converted to a handle type from which it is derived (even if that derivation is several levels deep.) This is because the C++ object to which the derived handle type refers is a kind-of the object referred to by the base handle type. This type of conversion is called a handle downcast because it is casting down the hierarchy towards the base type.

Notes:

There is no conversion available from hbase to hderived. This is because the kind-of relationship between the C++ classes to which they refer is one way only.

Variables of any handle type may be assigned the constant handle value none to make that variable refer to no object.

Converting from base to derived types

As discussed above, there are no automatic conversions from base types to derived types since this kind of conversion cannot be guaranteed to be valid. However, in some circumstances this type of conversion is desirable.

If you have a handle which you know refers to an instance of icShip but your handle is an hsim, you cannot use functionality specific to the ship. In this case you may want to convert your handle to an hship to use the ship-specific functionality. This type of conversion is called a handle upcast because it is casting up the hierarchy towards the derived class.

The package which defines your derived handle type may provide a cast function which you can use to perform the upcast. For example, the package iShip exports the following function:

prototype hship iShip.Cast( hobject o );

This function will return the value of o (but with the type hship) if the object to which o refers really is an instance of icShip. If this is not the cast, it will return the value none.

Example of use:

//
// Place the sim with respect to the marker. If the sim is also
// a ship then make it formate with the marker as well.
//
place_and_formate( hsim sim, hsim marker, float x, float y, float z )
{
    hship ship;

    // Place the sim
    Sim.PlaceRelativeTo( sim, marker, x, y, z );

    // Cast the sim to a ship
    ship = iShip.Cast( sim );

    // If the sim is a ship
    if ( ship != none )
    {
        // Give it the formate order as well
        iAI.GiveFormateOrder( ship, marker, x, y, z );
    }
}

Handle types and their Derivations

Handle Type | Purpose | Derived From | Defining Package
hbody | I-War 2 planetary body. | hmapentity | iBody
hcargo | I-War 2 item of cargo. | hobject | iCargo
hdockport | I-War 2 dockport on a ship. | hsubsim | iDockport
hemail | I-War 2 Email. | hobject | iEmail
hfaction | I-War 2 faction. | hobject | iFaction
hgroup | Handle to a Group of hsims. | hobject | Group
hhabitat | I-War 2 habitat (space station). | hmapentity | iHabitat
hinifile | INI file. | hobject | INIFile
hisim | I-War 2 sim | hsim | iSim
hlagrangepoint | I-War 2 Lagrange Point. | hmapentity | iLagrangePoint
hlock | Flux script lock. | hobject | Lock
hmapentity | I-War 2 map entity. | hisim | iMapEntity
hobject | The basic handle type. | None | None
hregion | I-War 2 region. | hobject | iRegion
hship | I-War 2 ship | hisim | iShip
hsim | Flux sim | hobject | Sim
hstate | Flux Pog script state. | hobject | State
hsubsim | Flux Subsim | hobject | Subsim
htrade | I-War 2 trade item. | hobject | iTrade
hwindow | GUI window handle. | hobject | GUI


Resource URLs

Flux searches for resources in the game's resource tree. The resource tree is defined by a series of search paths in the game's INI file. The paths specify roots of trees which are searched in sequence for each resource.

Typically, there will be a core resource tree, and then variations for language-specific content in separate directories. There may also be content from addons.

To locate resources, the game uses a URL-style mechanism. A resource URL looks like the following:

type:/path/to/file/filename

Notes:
The filename does not have an extension. The game infers the extension from the type of resource, and may be able to load several file types for one resource type (e.g. loading different image formats via the bitmap resource type.)

For certain types of data, which do not become objects, the resource manager is used to search for filenames directly. In this case the resource type should be the extension of the file to find. An example of this type of data is a ship template - it is used to define the ship and then thrown away. This is different to a texture, which is loaded from a file and then becomes a shared resource object in memory.

Resource URLs are not case sensitive. When a URL is specified to the game it is converted to lower case, and any backslash characters are converted to URL-style forward slashes. You can minimise the amount of work the game has to do by specifying resource URLs in this form, and ensure they are consistent with the look of everybody's code.

Example URLs

texture:/images/logos/flux

model:/avatars/command_section/CommandSectionRTO_T

ini:/sims/ships/player/comsec


Flux Classes

The Flux engine and games using Flux are written in C++. C++ is an object- orientated language. This means that data and code can be bound together into an object. Instead of having functions which operate on data, C++ presents objects which have methods for operating on their own contents.

Instances of classes

Each C++ object is said to be an instance of a C++ class. A class is like a patten for creating an object. It says that the object has a certain set of member variables (data) and a certain set of methods (code). Class instances share code, but each instance can store its own values in its data members.

For example, the following class represents a person:

class Person
{
    // Methods
    void SetName( char *name );
    void GetOlder( int how_many_years );

    // Member variables
    int _age;
    char *_name;
};

Different instances of the class person may have different names and ages, but they all have a name and an age. They are all examples of the same pattern.

Class hierarchy

Classes may be arranged in a hierarchy. When a class is defined it may be specified as deriving from another class which has previously been defined. A class of this type is called a derived class and the class from which it is derived is said to be its base class.

When a class derives from another class, it includes all the methods and data defined in the base class, and can then add its own methods and data.

As an example, the following classes are derived from class Person which was defined above.

// This class is derived from Person
class EnglishPerson : public Person
{
    // Additional methods
    void EatFishAndChips( bool salt, bool vinegar );

    // Additional member variables
    int _bowler_hat_size;
};

// This class is also derived from Person
class FrenchPerson : public Person
{
    // Additional methods
    void SmokeGitanes( int how_many_packets );

    // Additional member variables
    int _onion_count;
};

Each of these derived classes can do everything a Person can do (since they inherit methods from Person.) In addition, each instance of these classes is everything an instance of Person is, since they inherit member variables from Person. This means they all have a name, and can all grow older, because they are all kinds-of Person.

This kind-of relationship is the heart of the class hierarchy. It says that instances of derived classes can be treated as instances of their base class. An instance of FrenchPerson is a kind-of Person and can be treated as such.

The converse relationship is not true. A Person knows nothing about begin a FrenchPerson and cannot therefore smoke Gitanes.

Flux classes

Flux uses naming conventions for its C++ classes. These conventions will help you recognise class names which are sometimes used in Pog script code. C++ classes from the Flux engine itself are normally called FcSomeClass. Classes specific to a particular game will use a different letter to 'F'. For example, I-War 2 classes begin with the letter 'i', such as icShip.

The Flux class hierarchy is large and quite complex. All Flux classes are ultimately derived from the fundamental base class FcObject The part of the hierarchy of most interest to script programmers is the tree of classes derived from FiSim. This is the base class of all Sims, i.e. all objects which can exists in the game world.


Pog Header Files

Overview

A Pog header file is a text file associated with a Pog script with a list of all the functions and enumerations that Pog script exports for use in other packages.

It's used to provide information to the Pog compiler so that functions and enumerations in other packages can be linked during the compilation process.

When you compile a Pog script the compiler will automatically generate a header file for you. However this is not always accurate, so it is best to create your own.

A header file has the extension .h, e.g. myscript.h

See Header File Reference for details of the header files suppled with the Pog SDK.

Structure

Pog header files follow this structure:

Dependencies
This is optional, and most Pog headers don't contain them. The dependencies are the same ones that are defined in the dependencies of your Pog script. See Pog Script Structure for details.

Enumerations
Any enumerations you wish other packages to access must be placed here.

Prototypes
The functions you wish to allow other packages to use. Note that unlike prototypes in your script you must specify the package name as well as the function name, i.e. iExample.MyFunction

Example Header File

// Header file for Example Package
// Dependencies ////////////////////////////////////////////////////////////////
uses iSim, iShip, Math
// Enumerated types ////////////////////////////////////////////////////////////
enum eEnumExample
{
    EX_Example1,
    EX_Example2,
}

// Functions ///////////////////////////////////////////////////////////////////
prototype set iExample.ExampleFunction( int count, eEnumExample example );
prototype task iExample.ExampleTask();
prototype int iExample.CountExamples( list example_list );
// EOF


Debug and Atomic Blocks

Debug Blocks

Debug blocks are a mechanism for specifying debug code in a Pog script that will execute when the game is in developer mode.

Debug blocks are defined using the debug command.

Here is an example of a debug block:

debug
{
    Debug.PrintString( "This code only executes" );
    Debug.PrintString( "if the game is in debug mode." );
    count = count + 1;
    iSim.SetIndestructable( player_ship );
}

If only a single line is required to be a debug line, then the braces may be omitted:

debug Debug.PrintString( "This code only executes if the game is in debug mode." );

Note: The compiler will generate a warning if a statement from the Debug package is used outside of a debug block.

Important:
Be very careful with the code you place in a debug block, as it will only execute if the game is in developer mode. This means bugs could occur that only appear when you are in developer mode, or vice versa!

Atomic Blocks

Atomic blocks are used to ensure that code in a task function can operate without interference from other tasks, and all in one go.

For example, This debug code periodically prints a message "The event has occurred n times".

Debug.PrintString( "The event has occurred " );
Debug.PrintInt( count );
Debug.PrintString( " times.\n" );

In normal operation this will print the correct information, but if another task that's running simultaneously is also writing debug information to the log then you may get interference.

For example, another task (running at the same time) is using this debug code to periodically print out the name of a ship:

Debug.PrintString( "The name of the ship is " );
Debug.PrintString( ship_name );
Debug.PrintString( "\n" );

As the debug messages in the two tasks are composed of separate statements, the debug messages may get intertwined if the two tasks were to print to the log simultaneously, i.e.:

The event has occurred Dreadnaught
times.2

If you place each set of statements in an atomic block thus:

atomic
{
    Debug.PrintString( "The event has occurred " );
    Debug.PrintInt( count );
    Debug.PrintString( " times.\n" );
}

and:

atomic
{
    Debug.PrintString( "The name of the ship is " );
    Debug.PrintString( ship_name );
    Debug.PrintString( "\n" );
}

Then the two tasks will run the code atomically, so they can't interfere with each-other, so the result would be:

The event has occurred 2 times.
The name of the ship is Dreadnaught.

Important:
When code is running atomically all other tasks and functions are locked out. If a code in an atomic block were to get stuck in an infinite loop it would lock up the game.

For more information on Atomic behaviour and Tasks, see Multitasking.

Combining Debug and Atomic Blocks

Debug and atomic blocks can be combined by specifying both atomic and debug commands thus:

debug atomic
{
    Debug.PrintString( "The name of the ship is " );
    Debug.PrintString( ship_name );
    Debug.PrintString( "\n" );
}


Schedules

Overview

Schedules are a type of loop specific to Pog that executes code blocks at regular timed intervals. Schedules can only be used in task functions. See Multitasking for more details of tasks.

Schedules are useful when you wish to execute code at regular intervals, for example you might wish to check every second to see if a spaceship has reached a waypoint.

Defining a Schedule

A schedule takes the form:

// Schedule block start
schedule
{
    // This code block executes once per second.
    every 1 :
    {
        Debug.PrintString( "Hello!\n" );
    }
}

The schedule keyword defines the start of the schedule, while the every keyword defines the time interval in seconds that the schedule waits before executing the code block. You can use non-integer values, so an interval of 0.1 would be 1/10th of a second.

You can run multiple every blocks in the same schedule, with different time intervals, e.g.

schedule
{
    every 1 :
    {
        Debug.PrintString( "Hello\n" );
    }
    every 10 :
    {
        Debug.PrintString( "World!\n" );
    }
}

Exiting a Schedule
To exit a schedule use break as in switch statements and for / do / while loops. e.g.

schedule
{
    every 1 :
    {
        Debug.PrintString( "Hello\n" );
        if ( count == 10 ) break;
    }
}

You can also return from within a schedule.


Advanced Data Types

This page describes the advanced data types supported by Pog. For information on the basic types, refer to the fundamental data types pages.

These advanced types deal exclusively with collections of handles. See Handle Types for details of handles and their usage.

    Set types

    set
    A set is an un-ordered collection of unique handles. Each handle must be unique. Sets are manipulated using the flux Set package.

    List Type
    list
    A list is an ordered list of non-unique handles. Lists are manipulated using the flux List package.

    Group Type
    hgroup
    Not a true data type, as a group must be specially created using a command, a group is an ordered list of unique sim handles. Groups are manipulated using the flux Group package.


Object Properties and Death Scripts

Overview

Objects in flux have properties - numbers, strings or other data types attached to an object which can affect how it works.

Some properties are pre-set, and affect things like hit-points, speed, weapon damage, etc. Others can be added with Pog scripts. All properties can be queried by Pog, and most can be modified in-game in real-time. This allows you to instantly change how an object behaves in the game.

The Object package is used to for property manipulation. For details of the properties found on ships, weapons and other objects in the game, see the Graphic SDK.

Death Scripts

A very important property found on I-War 2 sims is called a death_script property. This property allows you to specify a script to execute when the object is killed. This is very useful for triggering special events on the death of a sim, such as special explosions, calling reinforcements, forcing a mission end, etc.

To set the death_script property use the Object.SetStringProperty command, with the string containing the function that's called when the sim dies, e.g.:

Object.SetStringProperty ( cargo_pod, "death_script", "iDeathScript.Antimatter" );

The function you wish to use as a death script must be specified in full with its package reference, e.g. iDeathScript.Antimatter, and the function must be exported in the Pog script that contains it.

When a death script executes the sim that it's running on will not be destroyed. It's up to the death script itself to destroy the sim.

To remove a death script from a sim, set the death_script property to an empty string, e.g

Object.SetStringProperty ( cargo_pod, "death_script", "" );

Death Script Script

Here is an example death script to show you how it's done. This one makes a sim blow up as if it contains antimatter.

task Antimatter( hsim sim )
{
    hsim blast = Sim.Create ( "ini:/sims/explosions/10km_antimatter_explosion", "Big Bang" );
    Sim.PlaceAt ( blast, sim );
    Sim.Destroy ( sim );
}

Note that the death script is a task, and you must specify the sim argument in the function. This will contain the handle of the sim that the death script is referring to.


States

Overview

A state is a means of saving a task between game sessions so that it can be restarted later.

Normally tasks disappear when a game session ends, such as if the game is quit, or the player transits from space into the player base, but a task with a state will be restarted when a new game session starts, as tasks with states are recorded in the save game. Tasks with states also automatically restart when the player leaves the player base and enters space.

Built into each state is a progress value. This value can be set by a script to define the progress through the state's associated task. The progress value can be used by custom Pog code to start the task at a point other than the beginning.

Additional properties can also be stored on a state using the Object functions. In this way it is possible to save a task's status more exactly, by storing properties that control how the task sets itself up. Again, specific Pog code needs to be written into the task to enable this.

When a Task with a state is no longer required its state must be destroyed to prevent it restarting again.

The State package is used to create, manipulate and destroy states.

Example

The following example code gives an example of a Pog script (in this case a mission) checking for a state and setting itself up accordingly.

// These are the enumerations for the states progress values for this script
enum eMissionState
{
    MS_Start = 1,
    MS_Part_1 = 2,
    MS_Part_2 = 3
};

// First get the state handle for the current task
hstate state = State.Find( Task.Current() );

// Then check if the state is valid.
if ( !state )
{
    // The state isn't valid, so create one with the progress value set to the beginning.
    state = State.Create( Task.Current(), MS_Start );
}
// Now we activate different code depending on the progress value of the state
switch( State.Progress( state ) )
{
    case( MS_Start ) :	// Code for the start of the mission would go here.
                break;

    case( MS_Part_1 ) :	// Code for the first part of the mission would go here.
                break;

    case( MS_Part_2 ) :	// Code for the second part of the mission would go here.
                break;
}


Pog Reserved Words

The following words are reserved for Pog use only, and cannot be used for variables, function names, or package names.

atomic
bool
break
case
const
continue
debug
default
do
else
enum
schedule
every  		false
float
for
if
int
handle
km
none
object
package
prototype
provides 		ref
return
start
string
switch
task
true
uses
void
while


Package reference

The package reference contains documentation for the Pog runtime library. This library is composed of a set of packages, which may be implemented with native code or with Pog scripts. The library is broken into a core section for the packages provided by the Flux engine itself, together with sections for the packages provided by specific games.

Note: POG Supports scripted packages, but the scripted packages supplied with I-War 2 are not documented here. Please refer to the header files for the scripted packages commands. A list of header files and their package purposes can be found in the Header File Reference section.

Package categories

  • Flux packages
  • I-War 2 packages


Flux packages
This page lists all the packages provided by the Flux engine. These packages are all independent of particular games. Most games will need to use these packages.

Language support packages

The following packages provide fundamental language support functionality. They are the Pog equivalent of the C++ standard libraries.
  • Debug
  • Math
  • Task

Data type packages

The following packages implement data types to extend Pog's built-in types. They also provide APIs for manipulating these data types.
  • Global
  • Group
  • List
  • Set
  • String

Game manipulation packages

The following packages provide APIs for examining and manipulating the game environment. Since these are core Flux packages, such manipulations cannot access game-specific data or functionality.

  • CDAudio

  • Config

  • Debug

  • GUI
  • INIFile
  • Input
  • Lock
  • Object
  • Sim
  • State
  • Stream
  • Subsim
  • Task
  • Text


Debug Package

The debug package provides a means to output trace messages and query the developer mode.

Functions:

  • DeveloperMode
  • PrintFloat
  • PrintInt
  • PrintString
  • PrintHandle
  • Break
  • Error

Notes:

Trace messages are output to the log file that is specified in the application configuration file under 'Debug'.


Debug.Break

Breaks into program execution.

prototype void Debug.Break();

Parameters:
None.

Return value:
None.

Notes:
This function breaks into program execution. If it is being run under a debugger, execution will pause and the debugger will display the line of code about to be executed.

Execution can be resumed by selecting 'run' from the debugger.

Note that this function only operates in a debug build of the game - otherwise it will simply do nothing.


Debug.DeveloperMode

Query the developer mode.

prototype bool Debug.DeveloperMode( );

Parameters:
None

Return value:
Boolean indicating the developer mode status. TRUE means that the developer mode is on.


Debug.Error

Bring up an error message in a window.

prototype void Debug.Error( string message );

Parameters:
message : The error message to display.

Return value:
None.

Notes:
This function pauses program execution and brings up a dialog box containing the given error. The message box will give you the option of dropping into a debugger and viewing the code being executed.

If dismissed, program execution continues normally.

Note that this function only operates in a debug build of the game - otherwise it will simply do nothing.


Debug.PrintFloat

Print the float to the console and log file.

prototype void Debug.PrintFloat( float output );

Parameters:
output : The output to be sent to be sent to the console and log file.

Return value:
None.

See also:
Debug.PrintInt, Debug.PrintString, Debug.PrintHandle.


Debug.PrintHandle

Print the handle to the console and the log file.

prototype void Debug.PrintHandle( hobject handle );

Parameters:
handle : The handle to be sent to the console and log file.

Return value:
None.

Notes:
This function will send a debugging message to the console and to the log file.

The output will be the value of the handle and, if the handle is to a valid Flux object, the name of the object and that object's class.

See also:
Debug.PrintFloat, Debug.PrintInt, Debug.PrintString.


Debug.PrintInt

Print the integer to the console and the log file.

prototype void Debug.PrintInt( int output );

Parameters:
output : The output to be sent to be sent to the console and log file.

Return value:
None.

See also:
Debug.PrintFloat, Debug.PrintString, Debug.PrintHandle.


Debug.PrintString

Print a string to the console and log file.

prototype void Debug.PrintString( string output );

Parameters:
output : The output to be sent to be sent to the console and log file.

Return value:
None.

See also:
Debug.PrintFloat, Debug.PrintInt, Debug.PrintHandle.


Math Package

Pog mathmatical functions.

Functions:

  • Abs
  • Clamp
  • Cos
  • CubeRoot
  • Power
  • Random
  • RandomInt
  • Sign
  • Sin
  • Sqrt
  • Tan

Notes:

All the angle parameters in this package are in degrees and not radians as found in C.


Math.Abs

Find the absolute value of f.

prototype int float Math.Abs( float f );

Parameters:
f : The value of which to find the absolute.

Return value:
Returns a float which is the absolute value of f.


Math.Clamp

Clamp f so that it lies in the range min to max.

prototype float Math.Clamp( float f,
                            float min,
                            float max );

Parameters:
f : The value of which to clamp.
min : The minimum value in the clamp range.
max : The maximum value in the clamp range.

Return value:
Returns the clamped value.


Math.Cos

Find the cosine of degrees.

prototype float Math.Cos( float degrees );

Parameters:
degrees : The angle in degrees.

Return value:
Returns a float which is the result of the cosine function.

Notes:
The result is in degrees.

See also:
Math.Sin, Math.Tan.


Math.Power

Find f to the power of exponent.

prototype float Math.Power( float f,
                            float exponent );

Parameters:
f : The number of which to find the power.
exponent : The exponent of the power function.

Return value:
Returns a float which is the result of the power function.

See also:
Math.Sqrt, Math.CubeRoot


Math.Random

Calculates a random number in a given range.

prototype float Math.Random( float min,
                             float max );

Parameters:
min : The lower bound of the range to randomise within.
max : The upper bound of the range to randomise within.

Return value:
A random number in the (inclusive) range between min and max.

Notes:
Flux will generate an error if min is greater than max.

See also:
Math.RandomInt.


Math.Sign

Find the sign of f.

prototype float Math.Sign( float f );

Parameters:
f : The value of which to find the sign.

Return value:
Returns either -1.0, 0.0, or 1.0.


Math.Sin

Find the sine of degrees.

prototype float Math.Sin( float degrees );

Parameters:
degrees : The angle in degrees.

Return value:
Returns a float which is the result of the sine function.

Notes:
The result is in degrees.

See also:
Math.Cos, Math.Tan.


Math.Sqrt

Find the square root of the parameter.

prototype float Math.Sqrt( float f );

Parameters:
f : The number of which to find the square root.

Return value:
Returns a float which is the square root of f.

See also:
Math.Power, Math.CubeRoot


Math.Tan

Find the tangent of degrees.

prototype float Math.Tan( float degrees );

Parameters:
degrees : The angle in degrees.

Return value:
Returns a float which is the result of the tangent function.

Notes:
The result is in degrees

See also:
Math.Sin, Math.Cos.


Math.RandomInt

Calculates a random integer in a given range.

prototype int Math.RandomInt( int min,
                              int max );

Parameters:
min : The lower bound of the range to randomise within.
max : The upper bound of the range to randomise within.

Return value:
A random number in the (inclusive) range between min and max.

Notes:
Flux will generate an error if min is greater than max.

See also:
Math.Random.


Math.CubeRoot

Find the cube root of the parameter.

prototype float Math.Sqrt( float f );

Parameters:
f : The number of which to find the cube root.

Return value:
Returns a float which is the cube root of f.

See also:
Math.Power, Math.Sqrt


Task

The Task package provides facilities for accessing and manipulating script tasks.

Functions:

  • Call
  • Cast
  • Current
  • Detach
  • Halt
  • IsSuspended
  • IsRunning
  • IsHalted
  • Resume
  • ResumeAll
  • Sleep
  • Start
  • Suspend

  • SuspendAll

Notes:

The functions in this package use the built-in type htask to refer to task objects.

If you are using the task query functions Task.IsSuspended, Task.IsSuspended or Task.IsHalted, you may find this summary of tasks states and query results useful.

See Multitasking for more information.


Task.Cast

This is the cast function for htask.

prototype htask Task.Cast( hobject o );

Parameters:
o : The object handle to cast.

Return value:
If o is the handle of a valid C++ object, and that object is a task (an instance of the C++ class FcScriptTask,) then o can be interpreted as a task handle. The return value is then the value of o, but with the type htask.

If o is not the handle of a valid C++ object, or that object is not a task, then the return value is none.


Task.Call

Call a specified function. The function must take no arguments and return no value.

prototype Task.Call( string f );

Parameters:
f : The function to call.

Return value:
None.

Notes:
Call a specified function. The function must take no arguments and return no value.

See also:
Task.Start


Task.Detach

This function detaches a task from its parent. The task will then not be halted and destroyed when the parent task is destroyed.

prototype Task.Detach( htask t );

Parameters:
t : The task to detach.

Return value:
None.

Notes:
A detached task becomes a new top-level (parentless) task. No association remains between the detached task and its erstwhile parent. The children of the detached task remain its children when it is moved to the top level.

Detaching a top-level task has no effect.

Any task can be detached, and the detach call can be made from anywhere. Typically a function or task which starts new tasks and then terminates will detach the new tasks as soon as it creates them, to ensure that they are not destroyed when it exits.


Task.Current

This function returns the handle of the task currently executing. That is, the handle of the task which calls Task.Current.

prototype htask Task.Current();

Parameters:
None.

Return value:
The handle of the task currently executing.


Task.Halt

Cause the specified task to stop execution immediately. Once the task has been halted, it is destroyed and cannot be resumed.

prototype Task.Halt( htask t );

Parameters:
t : The task to halt.

Return value:
None.

Notes:
To pause execution of a task, such that it is not destroyed and can be later resumed, use the function Task.Suspend.

See also:
Task.Suspend.


Task.IsHalted

This function returns the halted state of a specified task.

prototype bool Task.IsHalted( htask t );

Parameters:
t : The task to query.

Return value:
The return value is true if the task t is halted, or if t is not the handle of a valid task. The return value is false if the task is not halted.

Notes:
For more information on the possible combinations of queries and states, see this table.

See also:
Task.IsSuspended, Task.IsRunning, Task.Halt.


Task.IsRunning

This function returns the running state of a specified task.

prototype bool Task.IsRunning( htask t );

Parameters:
t : The task to query.

Return value:
The return value is true if the task t is currently running (this does not mean that the task is executing code at the moment but merely that is is not suspended or halted.). The return value is false if t is not running, or not the handle of a valid task.

Notes:
For more information on the possible combinations of queries and states, see this table.

See also:
Task.IsSuspended, Task.IsHalted, Task.Suspend, Task.Resume.


Task.IsSuspended

This function returns the suspended state of a specified task.

prototype bool Task.IsSuspended( htask t );

Parameters:
t : The task to query.

Return value:
The return value is true if the task t is currently suspended, and false if t is not suspended, or not the handle of a valid task.

A task which has been suspended by a call to Task.Sleep is suspended for the purposes of this query.

Notes:
For more information on the possible combinations of queries and states, see this table.

See also:
Task.IsRunning, Task.IsHalted, Task.Suspend, Task.Resume.


Task.Resume

This function resumes execution of a specified task.

prototype Task.Resume( htask t );

Parameters:
t : The task to resume.

Return value:
None.

Notes:
Task.Resume causes a suspended task to continue its execution. It has no effect on a task which is not suspended.

Resume and suspend calls for a task do not have cumulative effects. No matter how many times a task has been resumed, one call to Task.Suspend will suspend the task. Likewise, no matter how many times a task has been suspended, one call to Task.Resume will cause that task to resume execution.

See also:
Task.ResumeAll, Task.Suspend, Task.Sleep.


Task.ResumeAll

This function resumes execution of all suspended tasks.

prototype Task.ResumeAll();

Parameters:
None

Return value:
None.

See also:
Task.Suspend, Task.Sleep. Task.Resume


Task.Sleep

This function causes a task to sleep (suspend execution) for a specified length of time. When the task has slept for the specified time its execution will be automatically resumed.

prototype Task.Sleep( htask t, float seconds );

Parameters:
t : The task which is to be put to sleep.
seconds : The length of time in seconds for which the task should sleep.

Return value:
None.

Notes:
Sleeping a task can be used execute code 'in the future'. For example, if you want to call a function x seconds from now, you could use the following code snippet:

// This is the function to be called 'in the future'
prototype event();

// This is the helper function which uses sleep
task delayed_event( float seconds )
{
    // Sleep
    Task.Sleep( Task.Current(), seconds );

    // Call function after delay
    event();
}

...

    // In client code, you use the helper like this:
    start delayed_event( 10 );

Preliminary documentation: Delayed task start may be added as a built-in Pog feature if demand is sufficient.

See also:
Task.Suspend, Task.Resume.


Task.Start

Start a specified task function. The function must take no arguments and return no value.

prototype Task.Start( string t );

Parameters:
t : The task to start.

Return value:
None.

Notes:
The function must take no arguments and return no value.

See also:
Task.Call


Task.Suspend

This function suspends execution of a specified task.

prototype Task.Suspend( htask t );

Parameters:
t : The task to suspend.

Return value:
None.

Notes:
Task.Suspend causes a task to pause its execution. Execution may be resumed with the Task.Resume function.

To stop a task executing and permanently destroy it, use the function Task.Halt.

Suspend and resume calls for a task do not have cumulative effects. No matter how many times a task has been resumed, one call to Task.Suspend will suspend the task. Likewise, no matter how many times a task has been suspended, one call to Task.Resume will cause that task to resume execution.

See also:
Task.SuspendAll, Task.Resume, Task.ResumeAll, Task.Sleep, Task.Halt.


Task.SuspendAll

This function suspends execution of all tasks.

prototype Task.SuspendAll();

Parameters:
None

Return value:
None.

See also:
Task.Suspend, Task.Resume, Task.Sleep, Task.Halt.


Task query summary

The following table summarises the possible task states and query function return values:
Query | Suspended | Halted | Result
IsSuspended |  |  | false
 | • |  | true
 |  | • | false
 | • | • | true
IsRunning |  |  | true
 | • |  | false
 |  | • | false
 | • | • | false
IsHalted |  |  | false
 | • |  | false
 |  | • | true
 | • | • | true

Notes:
Tasks which are suspended may have been suspended using either of the Task.Suspend or Task.Sleep functions.


Group

Groups are primarily an unordered collection of unique hsims sequentially stored in an array structure, the first hsim (index 0) can also be viewed as a "leader". This element (index 0) will always be maintained while there are hsims in the array.

In addition groups may also collect together a number of other unique groups (also using an sequentially ordered array structure) which we call sub-groups. This allows groups to be optionally linked into a hierarchically arranged tree.

Type definitions:

  • hgroup

Functions:

  • AddGroup
  • AddSim
  • Cast
  • Create
  • Depth
  • Destroy
  • Flatten
  • FromList
  • FromSet
  • GroupCount
  • Leader
  • NthGroup
  • NthSim
  • Parent
  • PromoteSim
  • RemoveGroup
  • RemoveNthGroup
  • RemoveNthSim
  • RemoveSim
  • Root
  • SimCount
  • TotalSimCount


Group.hgroup

This is a handle to a group object.

hgroup : hobject;

Notes:
Group handles are returned when a group is created.

See also:
Group.Create


Group.AddGroup

Adds a subgroup to a group.

prototype Group.AddGroup( hgroup group, hgroup addition );

Parameters:
group : The group to which addition is added.
addition : The group to add as subgroup.

Return value:
none

See also:
Group.RemoveGroup,Group.RemoveNthGroup.


Group.AddSim

Adds a sim to a group.

prototype Group.AddSim( hgroup group, hsim addition );

Parameters:
group : The group to which addition is added.
addition : The sim to add to the group.

Return value:
none

See also:
Group.RemoveSim,Group.RemoveNthSim.


Group.Cast

Casts a handle to an object to a handle to a group.

prototype hgroup Group.Cast( hobject handle );

Parameters:
handle : The object handle to cast to the group handle.

Return value:
Returns a handle to a group or none if the cast was unsuccessful.


Group.Create

Creates a new group.

prototype hgroup Group.Create( );

Parameters:
none

Return value:
Returns a handle to the newly created group.

Notes:
A handle should be maintained to the top group of the group tree. In other words the only time the handle can be safely forgotton is when a newly created group is added as a sub-group to another.
You will need to call Group.Destroy on all the top group handles in order to prevent memory leakage.
Remember a single group is also the top group of what is a one group tree.

See also:
Group.Destroy.


Group.Depth

Query the group object to find out how deep it is in any group tree it is a part of.

prototype int Group.Depth( hgroup group );

Parameters:
group : The group to query.

Return value:
Returns an integer which is the depth level (top most group is 0, child groups > 0) of this group in any group hierarchy it may be a part of.


Group.Destroy

Recursively destroys a group and all its subgroups.

prototype Group.Destroy( hgroup group, bool including_sims );

Parameters:
group : The top group of the group tree to be destroyed.
including_sims : If true then this will also destroy any sims found in groups to be destroyed.

Return value:
none

Notes:
Care should be taken in the use of the including_sims boolean. If set to true then the sims will be deleted.

See also:
Group.Create.


Group.Flatten

Flattens the group object, recursively removing all subgroups and adding their sims to the group object in question.

prototype Group.Flatten( hgroup group );

Parameters:
group : The group to flatten.

Return value:
none


Group.FromList

Converts a list to a group.

prototype hgroup Group.FromList( ref list the_list );

Parameters:
the_list : The list to convert.

Return value:
Returns a handle to a new group containing all the sim handles of the list.

See also:
Group.FromSet.


Group.FromSet

Converts a set to a group.

prototype hgroup Group.FromSet( ref set the_set );

Parameters:
the_set : The set to convert.

Return value:
Returns a handle to a new group containing all the sim handles of the set.

See also:
Group.FromList.


Group.GroupCount

Query the group object to find out how many subgroups exist in the collection

prototype int Group.GroupCount( hgroup group );

Parameters:
group : The group to query.

Return value:
Returns an integer which is the total number of groups in the collection.


Group.Leader

Query the group object to find the handle to the leader sim.

prototype hsim Group.Leader( hgroup group );

Parameters:
group : The group to query.

Return value:
Returns a handle to a leader sim (first sim in the group) or none if the group is devoid of sims.

See also:
Group.PromoteSim.


Group.NthGroup

Returns the nth subgroup of a group.

prototype hgroup Group.NthGroup( hgroup group, int subgroup );

Parameters:
group : The group to check.
subgroup : Index to the subgroup

Return value:
Returns a handle to the subgroup or none if index is out of range.


Group.NthSim

Returns the nth sim in a group.

prototype hsim Group.NthSim( hgroup group, int sim );

Parameters:
group : The group to check.
sim : Index of the sim.

Return value:
Returns a handle to the sim or none if index is out of range.


Group.Parent

Returns the parent group handle of the given group handle.

prototype hgroup Group.Parent( hgroup group );

Parameters:
group : The group to query

Return value:
Returns a handle to the parent group group or none if the group has no parent (is top most).

See also:
Group.Root.


Group.PromoteSim

Promotes a sim to leader of the given group.

prototype Group.PromoteSim( hgroup group, int sim );

Parameters:
group : The group involved in the promotion.
sim : An index to the sim to promote.

Return value:
none

See also:
Group.Leader.


Group.RemoveGroup

Removes a subgroup from a group.

prototype Group.RemoveGroup( hgroup group, hgroup group_to_remove );

Parameters:
group : The group from which removal is to occur.
group_to_remove : The group to remove.

Return value:
none

See also:
Group.AddGroup,Group.RemoveNthGroup.


Group.RemoveNthGroup

Removes the nth subgroup from a group.

prototype Group.RemoveNthGroup( hgroup group, int group_index );

Parameters:
group : The group from which removal is to occur.
group_index : The subgroup index (from 0) of the group to remove.

Return value:
none

See also:
Group.AddGroup,Group.RemoveGroup.


Group.RemoveNthSim

Removes the nth sim from a group.

prototype Group.RemoveNthSim( hgroup group, int sim_index );

Parameters:
group : The group from which removal is to occur.
sim_index : The sim index (from 0) of the sim to remove.

Return value:
none

See also:
Group.AddSim,Group.RemoveSim.


Group.RemoveSim

Removes a sim from a group.

prototype Group.RemoveSim( hgroup group, hsim sim_to_remove );

Parameters:
group : The group from which removal is to occur.
sim_to_remove : The sim to remove.

Return value:
none

See also:
Group.AddSim,Group.RemoveNthSim.


Group.Root

Returns the top most parent (root) group handle of the given group handle.

prototype hgroup Group.Root( hgroup group );

Parameters:
group : The group to query

Return value:
Returns a top most (root) handle of this groups parent ancestors.

See also:
Group.Parent.


Group.SimCount

Query the group object to find out how many sims exist in the collection

prototype int Group.SimCount( hgroup group );

Parameters:
group : The group to query.

Return value:
Returns an integer which is the total number of sims in the collection.

Notes:
Doesn't process subgroups. Use Group.TotalSimCount to find the total number of sims in a group and its subgroups.

See Also:
Group.TotalSimCount


Group.TotalSimCount

Query the group object to find out how many sims exist in the collection, including all sims in all subgroups of that group.

prototype int Group.TotalSimCount( hgroup group );

Parameters:
group : The group to query.

Return value:
Returns an integer which is the total number of sims in the including all sims in all subgroups of that group.


Global

The global package provides a store for global data to be placed within. See Global Variables for more information.

Type definitions:

  • eGlobalType
  • eGlobalAccess

Functions:

  • CreateInt
  • CreateFloat
  • CreateBool
  • CreateHandle
  • CreateString
  • CreateList
  • CreateSet
  • Destroy
  • Exists
  • Type
  • Int
  • Float
  • Bool
  • Handle
  • String
  • List
  • Set
  • SetAccess
  • SetInt
  • SetFloat
  • SetBool
  • SetHandle
  • SetString
  • SetList
  • SetSet


Global.eGlobalAccess

Ennumerator indicating type of access available to a global.

enum eGlobalAccess{ GA_Read = 0x01, GA_Write = 0x02 };

Values:
GA_Read specifies read only, whereas the GA_Write specifies read or write.

See also:
Global.eGlobalType.


Global.eGlobalType

Ennumeration showing the type of the global.

enum eGlobalType{ GT_Int,
                  GT_Float,
                  GT_Bool,
                  GT_Handle,
                  GT_String,
                  GT_List,
                  GT_Set };

Notes:
These are the only valid types of globals.

See also:
eGlobalAccess.


Global.Bool

Accessor for boolean global

prototype bool Global.Bool( string name );

Parameters:
name : Name of the global to retrieve.

Return value:
Returns the boolean value of the global.

Notes:
Returns false if the global doesn't exist.

See also:
Global.Int, Global.Float, Global.Handle, Global.String, Global.List, Global.Set.


Global.CreateBool

Create a boolean global and initialise.

prototype Global.CreateBool( string name,
                             int access,
                             bool initial_value );

Parameters:
name : The name of the global to create.
access : The access type of the global.
initial_value : The initial boolean value of the global.

Return value:
None.

Notes:
If a global already exists with this name it is overwritten, unless the original is read only.

See also:
Global.CreateInt, Global.CreateFloat, Global.CreateHandle, Global.CreateString, Global.CreateList, Global.CreateSet.


Global.CreateFloat

Create a floating-point global and initialise.

prototype Global.CreateFloat( string name,
                              int access,
                              float initial_value );

Parameters:
name : The name of the global to create.
access : The access type of the global.
initial_value : The initial floating-point value of the global.

Return value:
None.

Notes:
If a global already exists with this name it is overwritten, unless the original is read only.

See also:
Global.CreateInt, Global.CreateBool, Global.CreateHandle, Global.CreateString, Global.CreateList, Global.CreateSet.


Global.CreateHandle

Create a handel global and initialise.

prototype Global.CreateHandle( string name,
                               int access,
                               hobject initial_value );

Parameters:
name : The name of the global to create.
access : The access type of the global.
initial_value : The initial handle value of the global.

Return value:
None.

Notes:
If a global already exists with this name it is overwritten, unless the original is read only.

See also:
Global.CreateInt, Global.CreateFloat, Global.CreateBool, Global.CreateString, Global.CreateList, Global.CreateSet.


Global.CreateInt

Create an integer global and initialise.

prototype Global.CreateInt( string name,
                            int access,
                            int initial_value );

Parameters:
name : The name of the global to create.
access : The access type of the global.
initial_value : The initial integer value of the global.

Return value:
None.

Notes:
If a global already exists with this name it is overwritten, unless the original is read only.

See also:
Global.CreateFloat, Global.CreateBool, Global.CreateHandle, Global.CreateString, Global.CreateList, Global.CreateSet.


Global.CreateList

Create a list global and initialise.

prototype Global.CreateList( string name,
                             int access,
                             list initial_value );

Parameters:
name : The name of the global to create.
access : The access type of the global.
initial_value : The initial list object to be held in the global.

Return value:
None.

Notes:
If a global already exists with this name it is overwritten, unless the original is read only.

See also:
Global.CreateInt, Global.CreateFloat, Global.CreateBool, Global.CreateHandle, Global.CreateString, Global.CreateSet.


Global.CreateSet

Create a set global and initialise.

prototype Global.CreateSet( string name,
                            int access,
                            set initial_value );

Parameters:
name : The name of the global to create.
access : The access type of the global.
initial_value : The initial set object to be held in the global.

Return value:
None.

Notes:
If a global already exists with this name it is overwritten, unless the original is read only.

See also:
Global.CreateInt, Global.CreateFloat, Global.CreateBool, Global.CreateHandle, Global.CreateString, Global.CreateList.


Global.CreateString

Create a string global and initialise.

prototype Global.CreateString( string name,
                               int access,
                               string initial_value );

Parameters:
name : The name of the global to create.
access : The access type of the global.
initial_value : The initial string value of the global.

Return value:
None.

Notes:
If a global already exists with this name it is overwritten, unless the original is read only.

See also:
Global.CreateInt, Global.CreateFloat, Global.CreateBool, Global.CreateHandle, Global.CreateList, Global.CreateSet.


Global.Destroy

Destroys a global if it is present.

prototype Global.Destoy( string name );

Parameters:
string : Name of the global.

Return value:
None.

Notes:
If no global was present, no error is produced.


Globals.Exists

Queries for the existance of a specific global

prototype bool Global.Exists(  string name );

Parameters:
name : The name of the global to query for existance.

Return value:
A boolean indicating the presence/absence of the global.

Notes:
True indicates that the global is present.

See also:
Global.Type.


Global.Float

Accessor for floating-point global

prototype float Global.Float( string name );

Parameters:
name : Name of the global to retrieve.

Return value:
Returns the floating-point value of the global.

Notes:
Returns zero if the global doesn't exist.

See also:
Global.Int, Global.Bool, Global.Handle, Global.String, Global.List, Global.Set.


Global.Handle

Accessor for handle global

prototype handle Global.Handle( string name );

Parameters:
name : Name of the global to retrieve.

Return value:
Returns the handle value of the global.

Notes:
Returns a handle containing none if the global doesn't exist.

See also:
Global.Int, Global.Float, Global.Bool, Global.String, Global.List, Global.Set.


Global.Int

Accessor for integer global

prototype int Global.Int( string name );

Parameters:
name : Name of the global to retrieve.

Return value:
Returns the integer value of the global.

Notes:
Returns zero if the global doesn't exist.

See also:
Global.Float, Global.Bool, Global.Handle, Global.String, Global.List, Global.Set.


Global.List

Accessor for list global

prototype list Global.List( string name );

Parameters:
name : Name of the global to retrieve.

Return value:
Returns the list stored in the global.

Notes:
Returns an empty list if the global doesn't exist.

See also:
Global.Int, Global.Float, Global.Bool, Global.Handle, Global.String, Global.Set.


Global.Set

Accessor for set global

prototype set Global.Set( string name );

Parameters:
name : Name of the global to retrieve.

Return value:
Returns the set stored in the global.

Notes:
Returns an empty set if the global doesn't exist.

See also:
Global.Int, Global.Float, Global.Bool, Global.Handle, Global.String, Global.List.


Global.SetAccess

Sets the access type of a global

prototype Global.SetAccess( string name,
                         enum access );

Parameters:
name : The name of the global to set.
access : The access value to set.

Return value:
None.

See also:
 eGlobalAccess


Global.SetBool

Sets the contents of a global.

prototype Global.SetBool( string name,
                          bool value );

Parameters:
name : The name of the global to set.
value : The value with which to set the global.

Return value:
None.

Notes:
The global will only change if the global is of the same type. Globals must exist before they can be set.

See also:
Global.SetInt, Global.SetFloat, Global.SetHandle, Global.SetString, Global.SetList, Global.SetSet.


Global.SetFloat

Sets the contents of a global.

prototype Global.SetFloat( string name,
                           float value );

Parameters:
name : The name of the global to set.
value : The value with which to set the global.

Return value:
None.

Notes:
The global will only change if the global is of the same type. Globals must exist before they can be set.

See also:
Global.SetInt, Global.SetBool, Global.SetHandle, Global.SetString, Global.SetList, Global.SetSet.


Global.SetHandle

Sets the contents of a global.

prototype Global.SetHandle( string name,
                            handle value );

Parameters:
name : The name of the global to set.
value : The value with which to set the global.

Return value:
None.

Notes:
The global will only change if the global is of the same type. Globals must exist before they can be set.

See also:
Global.SetInt, Global.SetFloat, Global.SetBool, Global.SetString, Global.SetList, Global.SetSet.


Global.SetInt

Sets the contents of a global.

prototype Global.SetInt( string name,
                         int value );

Parameters:
name : The name of the global to set.
value : The value with which to set the global.

Return value:
None.

Notes:
The global will only change if the global is of the same type. Globals must exist before they can be set.

See also:
Global.SetFloat, Global.SetBool, Global.SetHandle, Global.SetString, Global.SetList, Global.SetSet.


Global.SetList

Sets the contents of a global.

prototype Global.SetList( string name,
                          list value );

Parameters:
name : The name of the global to set.
value : The value with which to set the global.

Return value:
None.

Notes:
The global will only change if the global is of the same type. Globals must exist before they can be set.

See also:
Global.SetInt, Global.SetFloat, Global.SetBool, Global.SetHandle, Global.SetString, Global.SetSet.


Global.SetSet

Sets the contents of a global.

prototype Global.SetSet( string name,
                         set value );

Parameters:
name : The name of the global to set.
value : The value with which to set the global.

Return value:
None.

Notes:
The global will only change if the global is of the same type. Globals must exist before they can be set.

See also:
Global.SetInt, Global.SetFloat, Global.SetBool, Global.SetHandle, Global.SetString, Global.SetList.


Global.SetString

Sets the contents of a global.

prototype Global.SetString( string name,
                            string value );

Parameters:
name : The name of the global to set.
value : The value with which to set the global.

Return value:
None.

Notes:
The global will only change if the global is of the same type. Globals must exist before they can be set.

See also:
Global.SetInt, Global.SetFloat, Global.SetBool, Global.SetHandle, Global.SetList, Global.SetSet.


Global.String

Accessor for string global

prototype string Global.String( string name );

Parameters:
name : Name of the global to retrieve.

Return value:
Returns the string stored in the global.

Notes:
Returns an empty string if the global doesn't exist.

See also:
Global.Int, Global.Float, Global.Bool, Global.Handle, Global.List, Global.Set.


Global.Type

Query the type of the global.

prototype eGlobalType Global.Type( string name );

Parameters:
name : The name of the global to query for type.

Return value:
Returns an eGlobalType showing the type of the global.

Notes:
If the global does not exist then the engine will assert. Always check for existance first.

See also:
Global.Exists.


String

This package can be used to manipulate the built-in string data type.

Functions:

  • FormatInt
  • FormatStrStr
  • FromFloat
  • FromInt
  • Left
  • Length
  • Join
  • Mid
  • Right
  • ToInt
  • ToFloat
  • TrimLeft
  • TrimRight
  • Uppercase


String.FormatInt

Return a string formatted in the fprintf style. i.e.: the string contains exactly one %d or %u format specifier.

prototype string String.FormatInt( string text, int parameter );

Parameters:
text : A string.
paramter : An integer to place in the string.

Return value:
A string with the %d or %u substituted with the integer parameter.

See also:
String.FormatStrStr


String.FormatStrStr

Return a string formatted in the fprintf style. i.e.: the string contains exactly two %s format specifiers.

prototype string String.FormatStrStr( string text, string string_1, string string_2 );

Parameters:
text : A string.
string_1 : The first string to place at the first %s in the text string.
string_2 : The second string to place at the second %s in the text string.

Return value:
A string with the two %s substituted with the two string parameters.

See also:
String.FormatInt


String.FromFloat

Creates and returns a string of the given floating point value.

prototype string String.FromFloat( float float_param );

Parameters:
float_param : The value to set in the new string.

Return value:
A string containing the given floating point value.

See also:
String.FromInt, String.ToFloat, String.ToInt.


String.FromInt

Creates and returns a string from the given integer.

prototype string String.FromInt( int int_param );

Parameters:
int_param : The value to set in the newly created string.

Return value:
Returns a string containing the given integer.

See also:
String.FromFloat, String.ToFloat, String.ToInt.


String.Join

Join two strings together.

prototype string String.Join( string left,
                              string right );

Parameters:
left : The first string.
right : The second string.

Return value:
The concatonated string.

Notes:
Returns the result of attaching two string together in the order that they were passed in.


String.Left

Returns the left n characters of a given string, or the entire string if n is greater than the string's length.

prototype string String.Left( string text, int n,  );

Parameters:
text : A string.
n : The number of leftmost characters to return.

Return value:
Returns the n left characters as a string.

See also:
String.Right, String.Mid


String.Length

Returns the length of the given string.

prototype int String.Length( string text );

Parameters:
text : The string to find the length of.

Return value:
The length of the string.


String.Mid

Returns the middle most n characters of a string, starting at the given index.

prototype string String.Mid( string text, int first, int n );

Parameters:
text : A string.
first : The first character to return.
n : The number of characters to return from the first character specified.

Return value:
Returns the middle n characters as a string.

See also:
String.Left, String.Right


String.Right

Returns the right n characters of a given string, or the entire string if n is greater than the string's length.

prototype string String.Right( string text, int n,  );

Parameters:
text : A string.
n : The number of rightmost characters to return.

Return value:
Returns the n right characters as a string.

See also:
String.Left, String.Mid


String.ToFloat

Returns the floating point value stored in a given string.

prototype float String.ToFloat( string text );

Parameters:
text : A string containing a floating point value.

Return value:
Returns the floating point value stored in the given string.

See also:
String.FromFloat, String.FromInt, String.ToInt.


String.ToInt

Returns the integer stored in a given string.

prototype int String.ToInt( string text );

Parameters:
text : A string containing the integer to return.

Return value:
The integer value stored in the given string.

See also:
String.FromFloat, String.FromInt, String.ToFloat.


String.TrimLeft

Return a string excluding the leftmost n characters of the given string.

prototype string String.TrimLeft( string text, int n,  );

Parameters:
text : A string.
n : The number of leftmost characters to exclude from the string.

Return value:
Returns the string excluding the n leftmost characters.

See also:
String.TrimRight


String.TrimRight

Return a string excluding the rightmost n characters of the given string.

prototype string String.TrimRight( string text, int n,  );

Parameters:
text : A string.
n : The number of rightmost characters to exclude from the string.

Return value:
Returns the string excluding the n rightmost characters.

See also:
String.TrimLeft


String.UpperCase

Returns the upper case version of the given string.

prototype string String.UpperCase( string text );

Parameters:
text : A string you wish to convert to uppercase

Return value:
Returns the uppercase version of the given string.


List

Lists are a collection of sequentially ordered and nonunique items of type hobject.

Functions:

  • AddHead
  • AddTail
  • Append
  • Contains
  • FromSet
  • GetNth
  • Head
  • IsEmpty
  • ItemCount
  • Remove
  • RemoveAll
  • RemoveHead
  • RemoveTail
  • RemoveNth
  • RemoveMembers
  • SetNth
  • SortByFloatProperty
  • SortByHandle
  • SortByIntProperty
  • SortByStringProperty
  • Tail

Notes:

The handles can be added, removed, accessed, and queried using the above functions.


List.AddHead

Add an hobject item to the top of the sequentially ordered collection.

prototype List.AddHead( ref list the_list, hobject handle );

Parameters:
the_list : The list to which the handle is added.
handle : The handle to be added to the list.

Return value:
None.

See also:
List.AddTail, List.Append.


List.AddTail

Add an hobject item to the bottom of the sequentially ordered collection.

prototype List.AddTail( ref list the_list, hobject handle );

Parameters:
the_list : The list to which the handle is added.
handle : The handle to be added to the list.

Return value:
None.

See also:
List.AddHead, List.Append.


List.Append

Add the second sequentially ordered collection of hobject items to the tail of the first sequentially ordered collection.

prototype List.Append( ref list the_list, ref list other_list );

Parameters:
the_list : The list to which the other list is appended.
other_list : Another list object which is to be appended to the list.

Return value:
None.

See also:
List.AddHead, List.AddTail.


List.Contains

Query the list object to find out if a handle exits in the collection.

prototype bool List.Contains( ref list the_list hobobject the_handle );

Parameters:
the_list : The list object to query.
the_handle: The handle to check for.

Return value:
Returns a boolean indicating whether the handle exists in the collection.


List.FromSet

Create a nonunique sequentially ordered list collection from a set of unique elements.

prototype list List.FromSet( ref set the_set );

Parameters:
the_set : The set object to convert.

Return value:
Returns a list containing all the handle elements of the set.

See also:
Set.FromList.


List.GetNth

Retrieves the Nth item in the sequentially ordered list collection.

prototype hobject List.GetNth( ref list the_list, int index );

Parameters:
the_list : The list from which to retrieve the Nth item
index : Index of the item to be retrieved.

Return value:
Returns the hobject item found at the Nth location

Notes:
Most handles that are stored will probably be handles of a specific type and must be cast to the correct handle type before use.

See also:
List.Head, List.Tail.


List.Head

Retrieves the top item in the sequentially ordered list collection.

prototype hobject List.Head( ref list the_list );

Parameters:
the_list : The list from which to retrieve the head.

Return value:
Returns the hobject item found at the head of the list

Notes:
Most handles that are stored will probably be handles of a specific type and must be cast to the correct handle type.

See also:
List.GetNth, List.GetTail.


List.IsEmpty

Query the list collection object as to whether the collection is empty.

prototype bool List.IsEmpty( ref list the_list );

Parameters:
the_list : The list object to query.

Return value:
Returns a boolean indicating the empty status of the list object.

See also:
List.ItemCount.


List.ItemCount

Query the list object to find out how many items exist in the collection.

prototype int List.ItemCount( ref list the_list );

Parameters:
the_list : The list object to query.

Return value:
Returns an integer which is the total number of items in the collection.

See also:
List.IsEmpty.


List.Remove

Remove the hobject item from the collection.

prototype List.Remove( ref list the_list, hobject handle );

Parameters:
the_list : The list from which to remove the handle.
handle : The handle to be removed from the list.

Return value:
None.

See also:
List.RemoveAll, List.RemoveHead, List.RemoveTail, List.RemoveNth, List.RemoveMembers.


List.RemoveHead

Removes the head hobject item from the sequentially ordered collection.

prototype List.RemoveHead( ref list the_list );

Parameters:
the_list : The list from which to remove the head.

Return value:
None.

See also:
List.RemoveAll, List.Remove, List.RemoveTail, List.RemoveNth, List.RemoveMembers.


List.RemoveMembers

Remove the second collection of hobject items from the first.

prototype List.RemoveMembers( ref list the_list, ref list other_list );

Parameters:
the_list : The list from which to remove the members of the other list.
other_list : List of objects to be removed from the list.

Return value:
None.

See also:
List.RemoveAll, List.Remove, List.RemoveHead, List.RemoveTail, List.RemoveNth.

Copyright © 1999 - 2002 Particle Systems Ltd. All rights reserved.

list

Return Value
Returns a list containing the result of the command.

Parameters
the_list The list which the command takes as the source for applying the command.
other_list Another list object to be subtracted from the list.

Remarks
This command returns a list which is the result of the command being carried out on the_list. Therefore to carry out the command on the_list and to keep the result use the following syntax:

the_list = List.RemoveMembers( the_list, other_list );


List.RemoveNth

Remove the Nth item in the sequetially ordered collection.

prototype List.RemoveNth( ref list the_list, ref int index );

Parameters:
the_list : The list from which to remove the Nth item.
index : Index of item to remove.

Return value:
None.

See also:
List.RemoveAll, List.Remove, List.RemoveHead, List.RemoveTail, List.RemoveMembers.


List.RemoveTail

Removes the top hobject item from the sequentially ordered collection.

prototype List.RemoveTail( ref list the_list );

Parameters:
the_list : The list from which to remove the tail.

Return value:
None.

See also:
List.RemoveAll, List.Remove, List.RemoveHead, List.RemoveNth, List.RemoveMembers.


List.Tail

Retrieves the tail item in the sequentially ordered list collection.

prototype hobject List.Tail( ref list the_list );

Parameters:
the_list : The list from which to retrieve the tail.

Return value:
Returns the hobject item found at the tail of the list.

Notes:
Most handles that are stored will probably be handles of a specific type and must be cast to the correct handle type.

See also:
List.GetNth, List.Head.


List.SortByIntProperty

Return a list from the list sorted in numeric order of the value of the given int property

prototype list List.SortByIntProperty( ref list the_list, ref string_property );

Parameters:
the_list : The list object to query.
string_property : The int property on each object to sort by.

Return value:
Returns a list containing the sorted items.

See also:
List.SortByStringProperty, List.SortByFloatProperty, List.SortByHandle


List.SetNth

Sets the Nth item in the sequentially ordered list collection.

prototype void List.SetNth( ref list the_list, int index, hobobject the_handle );

Parameters:
the_list : The list from which to retrieve the Nth item
index : Index of the item to be set.
the_handle: The handle of the item to be set.

Return value:
None

See also:
List.AddHead, List.AddTail.


List.SortByStringProperty

Return a list from the list sorted in alphanumeric order of value the given string property.

prototype list List.SortByStringProperty( ref list the_list, ref string_property );

Parameters:
the_list : The list object to query.
string_property : The string defining the property on each object to sort by.

Return value:
Returns a list containing the sorted items.

See also:
List.SortByIntProperty, List.SortByFloatProperty, List.SortByHandle


List.RemoveAll

Removes all items from the list.

prototype List.RemoveAll( ref list the_list );

Parameters:
the_list : The list from which to remove all items.

Return value:
None.

See also:
List.Remove, List.RemoveHead, List.RemoveNth, List.RemoveMembers.


List.SortByFloatProperty

Return a list from the list sorted in numeric order of the value of the given float property

prototype list List.SortByFloatProperty( ref list the_list, ref string_property );

Parameters:
the_list : The list object to query.
string_property : The float property on each object to sort by.

Return value:
Returns a list containing the sorted items.

See also:
List.SortByStringProperty, List.SortByIntProperty, List.SortByHandle


List.SortByHandle

Return a list from the list sorted by handle ID.

prototype list List.SortByHandle( ref list the_list );

Parameters:
the_list : The list object to query.

Return value:
Returns a list containing the sorted items.

See also:

List.SortByStringProperty, List.SortByIntProperty, List.SortByFloatProperty


Set

Sets are an unordered collection of unique items of type hobject.

Functions:

  • Add
  • Union
  • Intersection
  • Difference
  • Remove
  • FirstElement
  • IsEmpty
  • ItemCount
  • Contains
  • FromList

Notes:

The handles can be added, removed, accessed, and queried using the above functions.


Set.Add

Add an hobject item to the set collection of unique handles.

prototype int Set.Add( ref set the_set, hobject handle );

Parameters:
the_set : The set to which the handle is added.
the_handle : The handle to be added to the set.

Return value:
None.

See also:
Set.Remove.

Copyright © 1999 - 2002 Particle Systems Ltd. All rights reserved.

set

Return Value
Returns a set containing the result of the command.

Parameters
the_set The set which the command takes as the source for applying the command.
handle

Remarks
This command returns a set which is the result of the command being carried out on the_set. Therefore to carry out the command on the_set and to keep the result use the following syntax:

the_set = Set.Add( the_set, handle );


Set.Contains

Query the set object to find out if a handle exits in the collection.

prototype bool Set.Contains( ref set the_set );

Parameters:
the_set : The set to query.

Return value:
Returns a boolean indicating whether the handle exists in the collection.


Set.Difference

Find the difference of the two sets. This creates a collection of those elements that are present in only one of the sets.

prototype Set.Difference( ref set set_one, ref set set_two );

Parameters:
set_one : Set to be used to find the difference with the other set.
set_two : Set to be used to find the difference with the other set.

Return value:
None.

Notes:
The first set will contain the set that is the difference.

See also:
Set.Intersection, Set.Union.


Set.FirstElement

Retrieves an item from the set collection.

prototype hobject Set.FirstElement( ref set the_set );

Parameters:
the_set : The set from which to retrieve an item.

Return value:
Returns an hobject item from the set.

Notes:
Most handles that are stored will probably be handles of a specific type and must be cast to the correct handle type before use.


Set.FromList

Create a unique collection of elements in a set from a list of ordered nonunique elements.

prototype Set.FromList( ref list the_list );

Parameters:
the_list : The list from which to make the set.

Return value:
None.

See also:
List.FromSet.


Set.Intersection

Find the intersection of the two sets. This creates a collection of those elements that are present in both sets.

prototype Set.Intersection( ref set set_one, ref set set_two );

Parameters:
set_one : Set to intersect with the other set.
set_two : Set to intersect with the other set.

Return value:
None.

Notes:
The set one will contain the result of the intersection.

See also:
Set.Difference, Set.Union.


Set.IsEmpty

Query the set collection object as to whether the collection is empty.

prototype bool Set.IsEmpty( ref set the_set );

Parameters:
the_set : The set to query.

Return value:
Returns a boolean indicating the empty status of the set object.

See also:
Set.ItemCount.


Set.ItemCount

Query the set object to find out how many items exist in the collection.

prototype int Set.ItemCount( ref set the_set );

Parameters:
the_set : The set object to query.

Return value:
Returns an integer which is the total number of items in the collection.

See also:
Set.IsEmpty.


Set.Remove

Remove the hobject item from the collection.

prototype Set.Remove( ref set the_set, hobject handle );

Parameters:
the_set : The set from which to remove the item
handle : The handle to be removed from the set.

Return value:
None.

See also:
Set.Add.


Set.Union

Find the union of the two sets. This is done by adding all the elements of the sets together, creating one collection of unique elements.

prototype Set.Union( ref set set_one, ref set set_two );

Parameters:
set_one : Set to find the union with the other set.
set_two : Set to find the union with the other set.

Return value:
None.

Notes:
The set one will return the union of the two sets.

See also:
Set.Difference, Set.Intersection.


CDAudio

The CDAudio package is used to control playback of audio from a CD, and additionally provides functions to query the CD Audio content of a CD disc.

Functions:

  • CurrentPosition
  • CurrentTrack
  • CurrentTrackPosition
  • DiskLength
  • IsCDAvailable
  • IsPlaying
  • NumberOfTracks
  • Open
  • Pause
  • Play
  • PlayStartEnd
  • PlayTrack
  • SetVolume
  • Stop
  • TrackEnd
  • TrackLeng th
  • TrackStart

Copyright © 2001 Particle Systems Ltd. All rights reserved.


CDAudio.CurrentPosition

Return the current position within the CD. This is the time from the beginning of the disk.

Returns 0 if the disk is not currently playing.

prototype float CDAudio.CurrentPosition();

Parameters:
None

Return value:
The current position within the CD as a floating point number.

Notes:
Returns 0 if the disk is not currently playing.

See also:
CDAudio.CurrentTrackPosition

Copyright © 2001 Particle Systems Ltd. All rights reserved.


CDAudio.CurrentTrack

Returns the the currently playing track.

prototype int CDAudio.CurrentTrack();

Parameters:
None.

Return value:
The track number as an int if a track is playing.
The enum S_Fail if no track is currently playing.

See also:
CDAudio.PlayTrack


CDAudio.CurrentTrackPosition

Return the current position into the current track

Returns 0 if the disk is not currently playing.

prototype float CDAudio.CurrentTrackPosition();

Parameters:
None

Return value:
The current position within the track as a floating point number.

Notes:
Returns 0 if the disk is not currently playing.

See also:
CDAudio.CurrentPosition, CDAudio.TrackStart, CDAudio.TrackEnd, CDAudio.TrackLength

Copyright © 2001 Particle Systems Ltd. All rights reserved.


CDAudio.DiskLength

Return the length (in seconds) of the CD.

prototype float CDAudio.DiskLength();

Parameters:
None.

Return value:
The length (in seconds) of the CD as a float.

See also:
CDAudio.NumberOfTracks, CDAudio.TrackLength


CDAudio.IsCDAvailable

Determine if there is a CD to play

prototype bool CDAudio.IsCDAvailable();

Parameters:
None

Return value:
TRUE if there is a CD to play.

FALSE if no CD is available..

See also:
CDAudio.IsPlaying


CDAudio.IsPlaying

Determine if a CD is currently playing

prototype float CDAudio.IsPlaying();

Parameters:
None

Return value:
TRUE if a CD is currently playing

FALSE if a CD is not playing.


CDAudio.NumberOfTracks

Returns the number of tracks on the CD.

prototype int CDAudio.NumberOfTracks();

Parameters:
None.

Return value:
The number of tracks on the CD as an int.

See also:
CDAudio.DiskLength


CDAudio.Open

Open (as in open file not open CD draw) the CD file system

Returns FALSE if there is no disc to play.

prototype bool CDAudio.Open();

Parameters:
None

Return value:
TRUE if there is a CD to open.

FALSE if no CD is available..

See also:
CDAudio.IsPlaying


CDAudio.Pause

Pause the CD. The CD can be restarted through Pause or Play

prototype CDAudio.Pause();

Parameters:
None.

Return value:
None.

See also:
CDAudio.Play


CDAudio.Play

Play the CD from the beginning, or continue play after a pause.

prototype bool CDAudio.Play();

Parameters:
None

Return value:
TRUE if there is a CD to play.

FALSE if no CD is available..

See also:
CDAudio.Pause, CDAudio.PlayTrack, CDAudio.PlayStartEnd


CDAudio.PlayStartEnd

Play the CD from the specified start time to the specified end time.

prototype bool CDAudio.PlayStartEnd( float start_time, float end_time );

Parameters:
start_time: The start time ( in seconds ).
end_time: The end time ( in seconds ).

Return value:
TRUE for success.
FALSE for failure.

See also:
CDAudio.Play, CDAudio.PlayTrack


CDAudio.PlayTrack

Play the given track.

prototype bool CDAudio.PlayTrack( int track );

Parameters:
track: The track to play.

Return value:
None

See also:
CDAudio.Pause, CDAudio.Play, CDAudio.PlayStartEnd


CDAudio.SetVolume

Set the current volume for CD output.

prototype bool CDAudio.SetVolume( float left, float right );

Parameters:
left: The left volume
right: The right volume

Return value:
None

Notes:
Volume is defined in the range [0..1].


CDAudio.Stop

Stop playing the CD. If Play is called subsequently then the CD will start at the beginning.

prototype CDAudio.Stop();

Parameters:
None.

Return value:
None.

See also:
CDAudio.Play


CDAudio.TrackEnd

Return the time at the end of the given CD track.

prototype float CDAudio.TrackEnd( int track );

Parameters:
track: The CD track

Return value:
The time (in seconds) at the end of the given CD track, as a float.

See also:
CDAudio.NumberOfTracks, CDAudio.DiskLength, CDAudio.TrackStart


CDAudio.TrackLength

Return the length (in seconds) of the current CD track.

prototype float CDAudio.TrackLength();

Parameters:
None.

Return value:
The length (in seconds) of the current CD track as a float.

See also:
CDAudio.NumberOfTracks, CDAudio.TrackStart, CDAudio.TrackEnd


CDAudio.TrackStart

Return the time at the start of the given CD track.

prototype float CDAudio.TrackStart( int track );

Parameters:
track: The CD track

Return value:
The time (in seconds) at the start of the given CD track, as a float.

See also:
CDAudio.NumberOfTracks, CDAudio.DiskLength, CDAudio.TrackEnd


Config

The Config package deals with the manipulation and querying of Flux configuration files.

Functions:

  • CountNumber
  • CreateBool
  • CreateFloat
  • CreateInt
  • CreateString
  • CreateVector
  • Exists
  • GetBool
  • GetFloat
  • GetInt
  • GetNumberedBool
  • GetNumberedFloat
  • GetNumberedInt
  • GetNumberedString
  • GetNumberedVectorX
  • GetNumberedVectorY
  • GetNumberedVectorZ
  • GetString
  • GetVectorX
  • GetVectorY
  • GetVectorZ
  • SetBool
  • SetFloat
  • SetInt
  • SetString
  • SetVector

Notes:

Flux uses configuration files to track various values. This package allows a scripter to use these files themselves. The files can be interrogated for values and values can be set.

Values in the configuration files are identified by a section and a key. A section and key uniquely defines one value so two sections in a config file can have identical keys.


Config.CountNumber

Determines the number of entries for a given key.

prototype int Config.CountNumber( string alias,
                              string section,
                              string key );

Parameters:
alias : The alias of the desired configuration file.
section : The name of the desired section in the configuration file.
key : The name of the desired key in the desired configuration file.

Return value:
Returns the number of entries for the key as an int.

Notes:
Flux will generate an error at runtime if the supplied alias does not match one of its registered config files.


Config.CreateBool

Creates a bool value in a new key in a section of a configuration file.

prototype void Config.CreateInt( string alias,
                                 string section,
                                 string key,
                                 int value );

Parameters:
alias : The alias of the configuration file.
section : The name of the desired section in the configuration file.
key : The name of the desired key in the configuration file.
value : The value to set in the configuration file.

Return value:
None.

Notes:
Flux will generate an error at runtime if the supplied alias does not match one of its registered config files.

This function can only be used to create a new value in the configuration file - if a value is already set for the given section and key then an error is generated by Flux.

See also:
Config.CreateFloat, Config.CreateString, Config.SetBool, Config.GetBool.

Copyright © 1999-2002 Particle Systems Ltd. All rights reserved.


Config.CreateFloat

Creates a float value in a new key in a section of a configuration file.

prototype void Config.CreateFloat( string alias,
                                   string section,
                                   string key,
                                   float value );

Parameters:
alias : The alias of the configuration file.
section : The name of the desired section in the configuration file.
key : The name of the desired key in the configuration file.
value : The value to set in the configuration file.

Return value:
None.

Notes:
Flux will generate an error at runtime if the supplied alias does not match one of its registered config files.

This function can only be used to create a new value in the configuration file - if a value is already set for the given section and key then an error is generated by Flux.

See also:
Config.CreateInt, Config.CreateString, Config.SetFloat, Config.GetFloat.


Config.CreateInt

Creates a integer value in a new key in a section of a configuration file.

prototype void Config.CreateInt( string alias,
                                 string section,
                                 string key,
                                 int value );

Parameters:
alias : The alias of the configuration file.
section : The name of the desired section in the configuration file.
key : The name of the desired key in the configuration file.
value : The value to set in the configuration file.

Return value:
None.

Notes:
Flux will generate an error at runtime if the supplied alias does not match one of its registered config files.

This function can only be used to create a new value in the configuration file - if a value is already set for the given section and key then an error is generated by Flux.

See also:
Config.CreateFloat, Config.CreateString, Config.SetInt, Config.GetInt.

Copyright © 1999-2002 Particle Systems Ltd. All rights reserved.


Config.CreateString

Creates a string value in a new key in a section of a configuration file.

prototype void Config.CreateString( string alias,
                                    string section,
                                    string key,
                                    string value );

Parameters:
alias : The alias of the configuration file.
section : The name of the desired section in the configuration file.
key : The name of the desired key in the configuration file.
value : The value to set in the configuration file.

Return value:
None.

Notes:
Flux will generate an error at runtime if the supplied alias does not match one of its registered config files.

This function can only be used to create a new value in the configuration file - if a value is already set for the given section and key then an error is generated by Flux.

See also:
Config.CreateFloat, Config.CreateInt, Config.SetString, Config.GetString.


Config.CreateVector

Creates a vector value in a new key in a section of a configuration file.

prototype void Config.CreateFloat( string alias,
                                   string section,
                                   string key,
                                   float x,
                                   float y,
                                   float z );

Parameters:
alias : The alias of the configuration file.
section : The name of the desired section in the configuration file.
key : The name of the desired key in the configuration file.
x : The x component of the vector to set in the configuration file.
y : The y component of the vector to set in the configuration file.
z : The z component of the vector to set in the configuration file.

Return value:
None.

Notes:
Flux will generate an error at runtime if the supplied alias does not match one of its registered config files.

This function can only be used to create a new value in the configuration file - if a value is already set for the given section and key then an error is generated by Flux.

See also:
Config.SetVector, Config.GetVectorX, Config.GetVectorY, Config.GetVectorZ.


Config.Exists

Determines whether or not a certain section and key has a value defined for it in the config file identified by the given alias.

prototype bool Config.Exists( string alias,
                              string section,
                              string key );

Parameters:
alias : The alias of the desired configuration file.
section : The name of the desired section in the configuration file.
key : The name of the desired key in the desired configuration file.

Return value:
Returns FALSE if Flux does not recognise the alias as a registered config file, or if no value is defined for the given key in the given section. If the alias is recognised and a value is defined for the given section and key then TRUE is returned.

Notes:
Flux will generate an error at runtime if the supplied alias does not match one of its registered config files.


Config.GetBool

Retrieves an bool value from a configuration file.

prototype int Config.GetBool( string alias,
                             string section,
                             string key );

Parameters:
alias : The alias of the configuration file.
section : The section to query.
key : The key to query.

Return value:
Returns the bool value at the given section and key, in the configuration file with the given alias.

Notes:
Flux will generate an error at runtime if the supplied alias does not match one of its registered config files.

If the alias is valid but the section and key have not been defined, then a default value of FALSE is returned.

See also:
Config.GetFloat, Config.GetString, Config.CreateInt, Config.SetInt, Config.SetBool.


Config.GetFloat

Retrieves a float value from a configuration file.

prototype float Config.GetFloat( string alias,
                                 string section,
                                 string key );

Parameters:
alias : The alias of the configuration file.
section : The section to query.
key : The key to query.

Return value:
Returns the float value at the given section and key, in the configuration file with the given alias.

Notes:
Flux will generate an error at runtime if the supplied alias does not match one of its registered config files.

If the alias is valid but the section and key have not been defined, then a default value of 0 is returned.

See also:
Config.GetInt, Config.GetString, Config.CreateFloat, Config.SetFloat.


Config.GetInt

Retrieves an integer value from a configuration file.

prototype int Config.GetInt( string alias,
                             string section,
                             string key );

Parameters:
alias : The alias of the configuration file.
section : The section to query.
key : The key to query.

Return value:
Returns the integer value at the given section and key, in the configuration file with the given alias.

Notes:
Flux will generate an error at runtime if the supplied alias does not match one of its registered config files.

If the alias is valid but the section and key have not been defined, then a default value of 0 is returned.

See also:
Config.GetFloat, Config.GetString, Config.CreateInt, Config.SetInt.


Config.GetNumberedBool

Retrieves an bool value from an array-style variable in a configuration file.

prototype int Config.GetNumberedBool( string alias,
                                     string section,
                                     string key,
                                     int number );

Parameters:
alias : The alias of the configuration file.
section : The section to query.
key : The key to query.
number : An array index to retrieve.

Return value:
Returns the bool value at the given index into the array style entry in the section and key, in the configuration file with the given alias.

Notes:
Flux will generate an error at runtime if the supplied alias does not match one of its registered config files.

If the alias is valid but the section and key have not been defined, then a default value of FALSE is returned.

This function is used to retrieve values from array-style entries in configuration file, such as:

[Section]
Key[0] = true
Key[1] = false
Key[2] = true
So, for example, Config.GetNumberedBool("Alias", "Section", "Key", 1 ) would return true.

See also:
Config.GetBool.


Config.GetNumberedFloat

Retrieves a float value from an array-style variable in a configuration file.

prototype float Config.GetNumberedFloat( string alias,
                                         string section,
                                         string key,
                                         int number );

Parameters:
alias : The alias of the configuration file.
section : The section to query.
key : The key to query.
number : An array index to retreive.

Return value:
Returns the float value at the given index into the array style entry in the section and key, in the configuration file with the given alias.

Notes:
Flux will generate an error at runtime if the supplied alias does not match one of its registered config files.

If the alias is valid but the section and key have not been defined, then a default value of 0 is returned.

This function is used to retrieve values from array-style entries in configuration file, such as:

[Section]
Key[0] = 0.1
Key[1] = 1.2
Key[2] = 2.3
So, for example, Config.GetNumberedFloat("Alias", "Section", "Key", 1 ) would return 1.2.

See also:
Config.GetFloat.


Config.GetNumberedInt

Retrieves an integer value from an array-style variable in a configuration file.

prototype int Config.GetNumberedInt( string alias,
                                     string section,
                                     string key,
                                     int number );

Parameters:
alias : The alias of the configuration file.
section : The section to query.
key : The key to query.
number : An array index to retreive.

Return value:
Returns the integer value at the given index into the array style entry in the section and key, in the configuration file with the given alias.

Notes:
Flux will generate an error at runtime if the supplied alias does not match one of its registered config files.

If the alias is valid but the section and key have not been defined, then a default value of 0 is returned.

This function is used to retrieve values from array-style entries in configuration file, such as:

[Section]
Key[0] = 12
Key[1] = 23
Key[2] = 34
So, for example, Config.GetNumberedInt("Alias", "Section", "Key", 1 ) would return 23.

See also:
Config.GetInt.


Config.GetNumberedString

Retrieves a string value from an array-style variable in a configuration file.

prototype string Config.GetNumberedString( string alias,
                                           string section,
                                           string key,
                                           int number );

Parameters:
alias : The alias of the configuration file.
section : The section to query.
key : The key to query.
number : An array index to retreive.

Return value:
Returns the string value at the given index into the array style entry in the section and key, in the configuration file with the given alias.

Notes:
Flux will generate an error at runtime if the supplied alias does not match one of its registered config files.

If the alias is valid but the section and key have not been defined, then a default value of 0 is returned.

This function is used to retrieve values from array-style entries in configuration file, such as:

[Section]
Key[0] = "Gouda"
Key[1] = "Edam"
Key[2] = "Cheddar"
So, for example, Config.GetNumberedString("Alias", "Section", "Key", 1 ) would return "Edam".

See also:
Config.GetString.


Config.GetNumberedVectorX

Retrieves the x coordinate of a vector value from an array-style variable in a configuration file.

prototype float Config.GetNumberedVectorX( string alias,
                                           string section,
                                           string key,
                                           int number );

Parameters:
alias : The alias of the configuration file.
section : The section to query.
key : The key to query.
number : An array index to retreive.

Return value:
Returns the float value of the x coordinate of the vector at the given index into the array style entry in the section and key, in the configuration file with the given alias.

Notes:
Flux will generate an error at runtime if the supplied alias does not match one of its registered config files.

If the alias is valid but the section and key have not been defined, then a default value of 0 is returned.

This function is used to retrieve values from array-style entries in configuration file, such as:

[Section]
Key[0] = (13.2, 16.5, 17.7)
Key[1] = (23.4, 22.6, 25.8)
Key[2] = (37.5, 37.7, 32.4)
So, for example, Config.GetNumberedVectorX("Alias", "Section", "Key", 1 ) would return 23.4.

See also:
Config.GetVectorX, Config.GetNuberedVectorY, Config.GetNuberedVectorZ.


Config.GetNumberedVectorY

Retrieves the y coordinate of a vector value from an array-style variable in a configuration file.

prototype float Config.GetNumberedVectorY( string alias,
                                           string section,
                                           string key,
                                           int number );

Parameters:
alias : The alias of the configuration file.
section : The section to query.
key : The key to query.
number : An array index to retreive.

Return value:
Returns the float value of the y coordinate of the vector at the given index into the array style entry in the section and key, in the configuration file with the given alias.

Notes:
Flux will generate an error at runtime if the supplied alias does not match one of its registered config files.

If the alias is valid but the section and key have not been defined, then a default value of 0 is returned.

This function is used to retrieve values from array-style entries in configuration file, such as:

[Section]
Key[0] = (13.2, 16.5, 17.7)
Key[1] = (23.4, 22.6, 25.8)
Key[2] = (37.5, 37.7, 32.4)
So, for example, Config.GetNumberedVectorY("Alias", "Section", "Key", 1 ) would return 22.6.

See also:
Config.GetVectorY, Config.GetNuberedVectorX, Config.GetNuberedVectorZ.


Config.GetNumberedVectorZ

Retrieves the z coordinate of a vector value from an array-style variable in a configuration file.

prototype float Config.GetNumberedVectorZ( string alias,
                                           string section,
                                           string key,
                                           int number );

Parameters:
alias : The alias of the configuration file.
section : The section to query.
key : The key to query.
number : An array index to retreive.

Return value:
Returns the float value of the z coordinate of the vector at the given index into the array style entry in the section and key, in the configuration file with the given alias.

Notes:
Flux will generate an error at runtime if the supplied alias does not match one of its registered config files.

If the alias is valid but the section and key have not been defined, then a default value of 0 is returned.

This function is used to retrieve values from array-style entries in configuration file, such as:

[Section]
Key[0] = (13.2, 16.5, 17.7)
Key[1] = (23.4, 22.6, 25.8)
Key[2] = (37.5, 37.7, 32.4)
So, for example, Config.GetNumberedVectorZ("Alias", "Section", "Key", 1 ) would return 25.8.

See also:
Config.GetVectorZ, Config.GetNuberedVectorX, Config.GetNuberedVectorY.


Config.GetString

Retrieves a string from a configuration file.

prototype string Config.GetString( string alias,
                                   string section,
                                   string key );

Parameters:
alias : The alias of the configuration file.
section : The section to query.
key : The key to query.

Return value:
Returns the string at the given section and key, in the configuration file with the given alias.

Notes:
Flux will generate an error at runtime if the supplied alias does not match one of its registered config files.

If the alias is valid but the section and key have not been defined, then a default value of 0 is returned.

See also:
Config.GetInt, Config.GetFloat, Config.CreateString, Config.SetString.


Config.GetVectorX

Retrieves the x component of a vector value from a configuration file.

prototype float Config.GetVectorX( string alias,
                                   string section,
                                   string key );

Parameters:
alias : The alias of the configuration file.
section : The section to query.
key : The key to query.

Return value:
Returns the x component of a vector value at the given section and key, in the configuration file with the given alias.

Notes:
Flux will generate an error at runtime if the supplied alias does not match one of its registered config files.

If the alias is valid but the section and key have not been defined, then a default value of 0 is returned.

See also:
Config.GetVectorY, Config.GetVectorZ, Config.CreateVector, Config.SetVector.


Config.GetVectorY

Retrieves the y component of a vector value from a configuration file.

prototype float Config.GetVectorY( string alias,
                                   string section,
                                   string key );

Parameters:
alias : The alias of the configuration file.
section : The section to query.
key : The key to query.

Return value:
Returns the y component of a vector value at the given section and key, in the configuration file with the given alias.

Notes:
Flux will generate an error at runtime if the supplied alias does not match one of its registered config files.

If the alias is valid but the section and key have not been defined, then a default value of 0 is returned.

See also:
Config.GetVectorX, Config.GetVectorZ, Config.CreateVector, Config.SetVector.


Config.GetVectorZ

Retrieves the z component of a vector value from a configuration file.

prototype float Config.GetVectorZ( string alias,
                                   string section,
                                   string key );

Parameters:
alias : The alias of the configuration file.
section : The section to query.
key : The key to query.

Return value:
Returns the z component of a vector value at the given section and key, in the configuration file with the given alias.

Notes:
Flux will generate an error at runtime if the supplied alias does not match one of its registered config files.

If the alias is valid but the section and key have not been defined, then a default value of 0 is returned.

See also:
Config.GetVectorX, Config.GetVectorY, Config.CreateVector, Config.SetVector.


Config.SetInt

Set an integer value in an existing key in an existing section of a configuration file.

prototype void Config.SetInt( string alias,
                              string section,
                              string key,
                              int value );

Parameters:
alias : The alias of the desired configuration file.
section : The name of the desired section.
key : The name of the desired key.
value : The value to set.

Return value:
None.

Notes:
Flux will generate an error at runtime if the supplied alias does not match one of its registered config files.

This function can only be used to set an existing value in the configuration file - if a value is not defined for the given section and key then an error is generated by Flux.

See also:
Config.SetFloat, Config.SetString, Config.CreateInt, Config.GetInt.


Config.SetFloat

Set a float value in an existing key in an existing section of a configuration file.

prototype void Config.SetFloat( string alias,
                                string section,
                                string key,
                                float value );

Parameters:
alias : The alias of the desired configuration file.
section : The name of the desired section.
key : The name of the desired key.
value : The value to set.

Return value:
None.

Notes:
Flux will generate an error at runtime if the supplied alias does not match one of its registered config files.

This function can only be used to set an existing value in the configuration file - if a value is not defined for the given section and key then an error is generated by Flux.

See also:
Config.SetInt, Config.SetString, Config.CreateFloat, Config.GetFloat.


Config.SetString

Set a string in an existing key in an existing section of a configuration file.

prototype void Config.SetString( string alias,
                                 string section,
                                 string key,
                                 string value );

Parameters:
alias : The alias of the desired configuration file.
section : The name of the desired section.
key : The name of the desired key.
value : The value to set.

Return value:
None.

Notes:
Flux will generate an error at runtime if the supplied alias does not match one of its registered config files.

This function can only be used to set an existing value in the configuration file - if a value is not defined for the given section and key then an error is generated by Flux.

See also:
Config.SetFloat, Config.SetInt, Config.CreateString, Config.GetString.


Config.SetVector

Set a vector value in an existing key in an existing section of a configuration file.

prototype void Config.SetVector( string alias,
                                 string section,
                                 string key,
                                 float x,
                                 float y,
                                 float z );

Parameters:
alias : The alias of the desired configuration file.
section : The name of the desired section.
key : The name of the desired key.
x : The x component of the vector to set.
y : The y component of the vector to set.
z : The z component of the vector to set.

Return value:
None.

Notes:
Flux will generate an error at runtime if the supplied alias does not match one of its registered config files.

This function can only be used to set an existing value in the configuration file - if a value is not defined for the given section and key then an error is generated by Flux.

See also:
Config.CreateVector, Config.GetVectorX, Config.GetVectorY, Config.GetVectorZ.


GUI

This package provides an interface to the Flux GUI. It allows you create GUI ready screens and fill those screens with GUI elements (that is to say, kinds of window).

Type definitions:

  • hwindow
  • Enumerations

Functions:

The GUI functions are extensive, so we've split the GUI help into sections.

Screen Manipulation and Handle Functions

Notes: A screen is a backdrop on which you create windows. There are several different classes of screen, each designed for a different purpose. An overlay is a screen with a transparent background, designed to overlay another screen.

Each screen that is created is placed onto a screen stack, with the most recent screen placed on top.

  • Cast

  • ClearAllScreens

  • CurrentScreenClassname

  • NumScreens

  • OverlayScreen

  • PopScreen
  • PopScreensTo
  • PushScreen
  • RemoveLastOverlay
  • RemoveOverlaysAfter
  • SetBackgroundImage
  • SetDefaultColour
  • SetDefaultFont
  • SetScreen

Window Manager Functions:

Notes: A window is an area you place on a screen. It can be any sort of user interface element, e.g. list boxes, text boxes, buttons, etc. Windows can also contain sub-windows called child windows.

  • DeselectWindow

  • FirstChild

  • FocusedWindow

  • FrameHeight
  • FrameWidth
  • NextSibling
  • RepositionWindow
  • SelectWindow
  • SetVisible
  • TopWindow
  • WindowTitle
  • WindowCanvasHeight
  • WindowCanvasWidth
  • WindowNeutralBlue
  • WindowNeutralGreen
  • WindowNeutralRed
  • WindowFocusedBlue
  • WindowFocusedGreen
  • WindowFocusedRed
  • WindowSelectedBlue
  • WindowSelectedGreen
  • WindowSelectedRed

Window Creation Functions:

Misc
  • CreateBackButton
  • CreateBorder
  • CreateButton
  • CreateFancyBorder
  • CreateStaticWindow

  • CreateWindow

  • DeleteWindow

  • SetButtonFunctionPog

  • SetButtonText

  • SetWindowClientArea
  • SetWindowFont
  • SetWindowTitle
  • SetWindowStateColours
  • SetWindowStateIcons
  • SetWindowStateTextures
  • SetWindowTextFormatting
Focus
  • CancelFocusLock
  • OnControlFocusCancel
  • OnControlFocusDown
  • OnControlFocusLeft
  • OnControlFocusRight
  • OnControlFocusSelect
  • OnControlFocusUp
  • SetControlFocusCancelFunction
  • SetFirstControlFocus
  • SetFocus
  • SetInputOverrideFunctions
  • SetWindowAcceptFocus
  • SetWindowNextFocus
  • SetWindowPreviousFocus
  • WindowNextFocus
  • WindowPreviousFocus
  • SetWindowAcceptFocus
Edit Boxes
  • CreateEditBox
  • EditBoxValue
  • SetEditBoxCursorToEnd
  • SetEditBoxMaxCharLength
  • SetEditBoxOverrides
  • SetEditBoxValue
Combo Boxes
  • AddComboBoxEntry
  • ComboBoxValue
  • ComboBoxValueIndex
  • CreateComboBox
List Boxes
  • AddListBoxEntry
  • CancelListBoxSelection
  • CreateListBox
  • DisableHighlight
  • ListBoxFocusedEntry
  • ListBoxSelectedIndex
  • ListBoxValue
  • ListBoxValueIndex
  • RemoveListBoxEntries
  • RemoveListBoxEntry
  • SelectListBoxEntry
  • SetListBoxFocusedEntry
  • SetListBoxGap
  • SetListBoxSelectFunction
Scrollbars
  • CreateDualScrollbars
  • CreateHorizontalScrollbar
  • CreateHorizontalScrollbarDecorator
  • ReattachScrollbar
  • CreateVerticalScrollbar
  • CreateVerticalScrollbarDecorator
CheckBoxes
  • CreateCheckbox
  • CheckBoxValue
Radio Buttons
  • CreateRadioButton
  • RadioButtonValue
  • SetRadioButtonChecked
Text Windows
  • CreateTextWindow
  • SetTextWindowResource
  • SetTextWindowString
  • TextWindowBack
Splitter Windows
  • CreateFancySplitterWindow
  • CreateSplitterWindow
  • SplitterWindowBottomWindow
  • SplitterWindowTopWindow
Shady Bars
  • SetShadyBarWidth
  • SetRHSShadyBarWidth
Sliders
  • CreateSliderControl
  • SliderControlValue
  • SetSliderControlValue

Sound Support Functions:

  • RegisterSound
  • QueueSound
  • PlaySound
  • StartSound
  • StopSound
  • SetBeepOnGainFocus

Move Playback

  • PlayBackgroundMovie
  • StopAllMovies
  • StopBackgroundMovie

Notes:

GUI screens are particular derivations of a base GUI-ready class. Each one will initialise with a Pog function. The functions in this package can be used to construct an interface on that screen.


hwindow

A handle to a Flux GUI element, a window.

hwindow : hobject;

Notes:
Window handles are used to refer to different kinds of windows, such as text boxes, checkboxes and combo boxes. It is up to the scripter to pass the expected window type into the functions in the GUI package. For example, calling GUI.CheckboxValue() with a window handle returned from GUI.CreateListBox() will fail.


GUI Enumerations

These are the enumerations used by the GUI package.

Sound

These enums are used to play the appropriate sound for the various beeps used in the GUI.

S_None
S_Minor
S_Confirm
S_Error
S_Loadout
S_MechConfirm
S_AddProgram
S_RemoveProgram
S_AddUpgrade
S_RemoveUpgrade

Icons

These enums define the icon types which can be used on customisable buttons

I_None
I_LeftArrowOn
I_LeftArrowOff
I_RightArrowOn
I_RightArrowOff
I_CircleOn
I_CircleOff
I_Count


GUI.Cast

Attempt to cast a handle up to a window handle.

prototype hwindow GUI.Cast( hobject object );

Parameters:
object : The handle to cast.

Return value:
A handle to a window or a null handle if the given handle was not a valid window object.

Notes:
It is safe to use this function to determine whether or not a handle is a handle to a valid window object.

See also:
GUI.hwindow.


GUI.ClearAllScreens

Pop all screens off the screen stack, destroying them.

prototype GUI.ClearAllScreens();

Parameters:
None.

Return value:
None.

Notes:
If this function is called, and no new screen is pushed onto the stack, the game will end.

See also:
GUI.PushScreen, GUI.PopScreen.


GUI.CurrentScreenClassname

Returns the classname of the topmost GUI screen

prototype string GUI.CurrentScreenClassname();

Parameters:
None

Return value:
Returns a string containing the classname of the current screen.

See also:
GUI.SetScreen


GUI.NumScreens

Get the number of screens (excluding overlays) on the screen stack.

prototype int GUI.NumScreens();

Parameters:
None

Return value:
Returns an int containing the number of the screens (excluding overlays) on the screen stack.


GUI.OverlayScreen

Overlays an instance of the given screen class onto the current screen.

prototype GUI.OverlayScreen( string screen_class );

Parameters:
screen_class : The name of the screen class to overlay.

Return value:
None.

Notes:
This function will fail if the given screen class is not a valid FiScreen derived class.

See also:
GUI.RemoveLastOverlay, GUI.RemoveOverlaysAfter


GUI.PopScreen

Pop the current screen off the screen stack, destroying it.

prototype void GUI.PopScreen();

Parameters:
None.

Return value:
None.

See also:
GUI.PushScreen, GUI.ClearAllScreens.


GUI.PopScreensTo

Pop screens until we run out, or reach the named screen.

prototype void GUI.PopScreensTo( string screen_class );

Parameters:
screen_class : The class of the screen to pop to..

Return value:
None.

See also:
GUI.PopScreen, GUI.PushScreen, GUI.ClearAllScreens.


GUI.PushScreen

Create a new screen of the given class and push it onto the screen stack, making it current.

prototype GUI.PushScreen( string screen_class );

Parameters:
screen_class : The name of the screen class to instantiate.

Return value:
None.

Notes:
This function will fail if the given screen class is not a valid FiScreen derived class.

See also:
GUI.PopScreen.


GUI.RemoveLastOverlay

Remove the last (i.e. top) overlay screen.

prototype GUI.RemoveLastOverlay();

Parameters:
None

Return value:
None.

See also:
GUI.OverlayScreen, GUI.RemoveOverlaysAfter


GUI.RemoveOverlaysAfter

Remove all overlays from the overlay list from the given class onwards.

prototype GUI.RemoveOverlaysAfter( string screen_class );

Parameters:
screen_class : The name of the screen class to start removing screens from.

Return value:
None.

Notes:
This function will fail if the given screen class is not a valid FiScreen derived class.

See also:
GUI.OverlayScreen, GUI.RemoveLastOverlay


GUI.SetBackgroundImage

Sets a background image for the current GUI screen.

prototype GUI.SetBackgroundImage( string image_resource,
                                  bool dim );

Parameters:
image_resource : Resource request for the desired image.
dim : Whether or not to dim the image.

Return value:
None.

Notes:
This function has only been tested with 256x256 images.

The image will be stretched to fit to the full screen size.


GUI.SetDefaultColour

Set the default colour for text and drawing on the screen..

prototype GUI.SetDefaultColour( float red, float green, float blue );

Parameters:
red : The red value of the colour.
green : The green value of the colour.
blue : The blue value of the colour.

Return value:
None.

Notes:
All colour values should be in the range of 0 to 1.


GUI.SetDefaultFont

Set the default font for the screen.

prototype GUI.SetDefaultFont( string font_request );

Parameters:
font_request : The resource filename of the font to use.

Return value:
None.


GUI.SetScreen

Set the given screen, at the expense of the current screen.

prototype GUI.SetScreen( string screen_class );

Parameters:
screen_class : The class of the screen to create set.

Return value:
None.

Notes:
Destroys the current screen. Then creates a screen of the given class and makes it the current screen.

See also:
GUI.PushScreen, GUI.PopScreen.


GUI.DeselectWindow

Deselect a window.

prototype GUI.DeselectWindow( hwindow window );

Parameters:
window : The window to deselect..

Return value:
None.

See Also
SelectWindow


GUI.FirstChild

Get the first child of the given window.

prototype GUI.FirstChild( hwindow window );

Parameters:
window : The window to get the first child from.

Return value:
None.


GUI.FocusedWindow

Get the currently focused window.

prototype hwindow GUI.FocusedWindow( hwindow focus );

Parameters:
None

Return value:
None.


GUI.FrameHeight

Get the height of the current GUI screen.

prototype int GUI.FrameHeight();

Parameters:
None.

Return value:
The height of the current screen, if it is a valid GUI screen. If it is not a valid GUI screen then 0 is returned.

See also:
GUI.FrameWidth.


GUI.FrameWidth

Get the width in frame units of the current screen, if that screen is a valid GUI screen.

prototype int GUI.FrameWidth();

Parameters:
None.

Return value:
The width, in frame units, of the current GUI screen. If the current screen is not a valid GUI screen then 0 is returned.

See also:
GUI.FrameHeight.


GUI.NextSibling

Get the next sibling of the current window.

prototype GUI.NextSibling( hwindow window );

Parameters:
window : The window to get the next sibling from.

Return value:
None.


GUI.RepositionWindow

Remove a window from its current parent and reset the window with a new parent and offset into that parent.

prototype hwindow GUI.CreateWindow( hwindow window, hwindow parent, int x_offset, int y_offset );

Parameters:

window : The window to move.
parent : The new parent.
x_offset : The x coordinate of the new window position.
y_offset : The y coordinate of the new window position.

Return value:
None.


GUI.SelectWindow

Select a window.

prototype GUI.SelectWindow( hwindow window );

Parameters:
window : The window to select..

Return value:
None.

See Also
DeselectWindow


GUI.SetVisible

Set a window visible / invisible.

prototype GUI.SetVisible( hwindow window, bool visible );

Parameters:
window : The window to set the next focus for.
visible : Boolean for visibility.

Return value:
None.


GUI.TopWindow

Get the top window from the current screen, if it is a valid GUI screen.

prototype hwindow GUI.TopWindow();

Parameters:
None.

Return value:
The top window of the current screen, if it is a valid GUI screen. If the current screen is not a GUI window this function will return a null handle.


GUI.WindowTitle

Return the title for a given window

prototype string GUI.WindowTitle( hwindow window );

Parameters:

window : The window to get the title from.

Return value:
The window title as a string.

See also:
SetWindowTitle


GUI.WindowCanvasWidth

Get the height of a window canvas.

prototype int GUI.WindowCanvasHeight( hwindow window );

Parameters:
window : The window to get the canvas height from.

Return value:
The height of the specified window's canvas as an int.


GUI.WindowCanvasWidth

Get the width of a window canvas.

prototype int GUI.WindowCanvasWidth( hwindow window );

Parameters:
window : The window to get the canvas width from.

Return value:
The width of the specified window's canvas as an int.


GUI.WindowFocusedBlue

Get the window's blue colour component for the focused state.

prototype float GUI.WindowFocusedBlue( hwindow window );

Parameters:
window : The window to get the colour value from.

Return value:
The colour value as an integer in the range of 0 - 1.


GUI.WindowFocusedGreen

Get the window's green colour component for the focused state.

prototype float GUI.WindowFocusedGreen( hwindow window );

Parameters:
window : The window to get the colour value from.

Return value:
The colour value as an integer in the range of 0 - 1.


GUI.WindowFocusedRed

Get the window's red colour component for the focused state.

prototype float GUI.WindowFocusedRed( hwindow window );

Parameters:
window : The window to get the colour value from.

Return value:
The colour value as an integer in the range of 0 - 1.


GUI.WindowNeutralBlue

Get the window's blue colour component for the neutral state.

prototype float GUI.WindowNeutralBlue( hwindow window );

Parameters:
window : The window to get the colour value from.

Return value:
The colour value as an integer in the range of 0 - 1.


GUI.WindowNeutralGreen

Get the window's green colour component for the neutral state.

prototype float GUI.WindowNeutralGreen( hwindow window );

Parameters:
window : The window to get the colour value from.

Return value:
The colour value as an integer in the range of 0 - 1.


GUI.WindowNeutralRed

Get the window's red colour component for the neutral state.

prototype float GUI.WindowNeutralRed( hwindow window );

Parameters:
window : The window to get the colour value from.

Return value:
The colour value as an integer in the range of 0 - 1.


GUI.WindowSelectedBlue

Get the window's blue colour component for the selected state.

prototype float GUI.WindowSelectedBlue( hwindow window );

Parameters:
window : The window to get the colour value from.

Return value:
The colour value as an integer in the range of 0 - 1.


GUI.WindowSelectedGreen

Get the window's green colour component for the selected state.

prototype float GUI.WindowSelectedGreen( hwindow window );

Parameters:
window : The window to get the colour value from.

Return value:
The colour value as an integer in the range of 0 - 1.


GUI.WindowSelectedRed

Get the window's red colour component for the selected state.

prototype float GUI.WindowSelectedRed( hwindow window );

Parameters:
window : The window to get the colour value from.

Return value:
The colour value as an integer in the range of 0 - 1.


GUI.CreateBackButton

Create a back button - like a normal button, but with added avatar.

prototype hwindow GUI.CreateBackButton( int x,
                                        int y,
                                        int width,
                                        int height,
                                        hwindow parent );

Parameters:
x : The x coordinate of the top left hand corner of the window in it's parent's canvas.
y : The y coordinate of the top left hand corner of the window in it's parent's canvas.
width : The width of the window.
height : The height of the window.
parent : The window to add the new window to as a child.

Return value:
Returns a handle to the new window, or a null handle if there were errors.

Notes:
This function creates a functionless button. It can be clicked on but will not be fully functional until the button click action is set as a Pog function.

It is also possible to set text centred on the button.

See also:
CreateButton, SetButtonFunctionPog, SetButtonText.


GUI.CreateBorder

Create a 'border' window element - a border around an existing window.

prototype hwindow GUI.CreateBorder( hwindow target );

Parameters:
target : The existing window to put a border around.

Return value:
A handle to the border GUI element, or a null handle if there was an error.

Notes:
The 'border' GUI element is a decorator. This means that it attaches to an existing window and cannot exist on its own.

When you attach a decorator to a window, the existing window becomes a child of the decorator rather than its previous parent. The decorator replaces the existing window as a child of the parent - the decorator 'pushes in' between the window and its parent.

There must be enough room in the canvas of the parent for the decorator to fit around the existing window. For example, if a window was in the far top left corner of its parent's canvas and was then decorated with a border there would not be enough room in the parent's canvas to fit the top and left portions of the border.

See Also
CreateFancyBorder


GUI.CreateButton

Create a normal 'button' GUI element, with it's top-left hand corner in the given position, with the given width and height (all in frame units) and with the given parent.

prototype hwindow GUI.CreateButton( int x,
                                    int y,
                                    int width,
                                    int height,
                                    hwindow parent );

Parameters:
x : The x coordinate of the top left hand corner of the window in it's parent's canvas.
y : The y coordinate of the top left hand corner of the window in it's parent's canvas.
width : The width of the window.
height : The height of the window.
parent : The window to add the new window to as a child.

Return value:
Returns a handle to the new window, or a null handle if there were errors.

Notes:
This function creates a functionless button. It can be clicked on but will not be fully functional until the button click action is set as a Pog function.

It is also possible to set text centred on the button.

See also:
GUI.SetButtonFunctionPog, GUI.SetButtonText, CreateBackButton


GUI.CreateFancyBorder

Create a fancy border around the given window

prototype hwindow GUI.CreateFancyBorder( hwindow target );

Parameters:
target : The existing window to put a border around.

Return value:
A handle to the border GUI element, or a null handle if there was an error.

See Also:
CreateBorder


GUI.CreateStatisticWindow

Create a static window - displays its title and an image

prototype hwindow GUI.CreateStaticWindow( int x, int y, int width, int height, hwindow parent );

Parameters:

x : The x coordinate of the top left hand corner of the window in it's parent's canvas.
y : The y coordinate of the top left hand corner of the window in it's parent's canvas.
width : The width of the window.
height : The height of the window.
parent : The window to add the new window to as a child.

Return value:
A handle to the window.

See also:
CreateWindow, DeleteWindow


GUI.CreateWindow

Create a basic window. It doesn't do anything, but it can be used to group radio buttons together (radio buttons group with their siblings).

prototype hwindow GUI.CreateWindow( int x, int y, int width, int height, hwindow parent );

Parameters:

x : The x coordinate of the top left hand corner of the window in it's parent's canvas.
y : The y coordinate of the top left hand corner of the window in it's parent's canvas.
width : The width of the window.
height : The height of the window.
parent : The window to add the new window to as a child.

Return value:
A handle to the window.

See also:
CreateStaticWindow, DeleteWindow


GUI.DeleteWindow

Delete the window with the given handle.

prototype GUI.DeleteWindow( hwindow window );

Parameters:
window : The window to delete.

Return value:
None.

See Also:
CreateWindow, CreateStaticWindow


GUI.SetButtonFunctionPog

Set the Pog function to execute when the button is clicked on.

prototype GUI.SetButtonFunctionPog( hwindow button,
                                    string pog_function );

Parameters:
button : The button to set.
pog_function : The Pog function to execute, in the form package.function.

Return value:
None.

See also:
GUI.CreateButton, CreateBackButton, GUI.SetButtonText.


GUI.SetButtonText

Set the text to display on the face of the button.

prototype GUI.SetButtonText( hwindow button,
                             string text,
                             string font );

Parameters:
button : The button to set.
string : The string to set on the face of the button.
font : The font to use to draw the button text.

Return value:
None.

See also:
GUI.CreateButton, GUI.SetButtonFunctionPog.


GUI.SetWindowClientArea

Set the window's client area. Will increase the canvas size if necessary.

prototype GUI.SetWindowClientArea( hwindow window, int left, int top, int right, int bottom );

Parameters:
window : The window to set.
left : Left coordinate
top : Top coordinate
right : Right coordinate
bottom : Bottom coordinate.

Return value:
None.


GUI.SetWindowFont

Set the font for a given window.

prototype GUI.SetWindowFont( hwindow window, string font_request );

Parameters:
window : The window to set the font for.
font_request : String containing the resource request string of the font.

Return value:
None.


GUI.SetWindowStateColours

Set the window colour for each of the four possible window states.

prototype GUI.SetWindowStateColours( hwindow customisable_window,
                    float n_red, float n_green, float n_blue,
                    float f_red, float f_green, float f_blue,
                    float s_red, float s_green, float s_blue );

Parameters:
window : The window to set the colour states for.
 n_red : Neutral state red component.
n_green : Neutral state green component.
n_blue : Neutral state blue component.
f_red : Focused state red component.
f_green : Focused state green component.
f_blue : Focused state blue component.
s_red : Selected state red component.
s_green : Selected state green component.
s_blue : Selected state blue component.

Return value:
None.

Notes:
The component values must be in the range of 0 - 1.


GUI.SetWindowStateIcons

Set icons for this window for the various window states.

prototype GUI.SetWindowStateIcons( hwindow window,
                    eIcon neutral,
                    eIcon focused,
                    eIcon selected );

Parameters:
customisable: The window to set the state icons for.
neutral : Enumerator for the neutral state icon.
focused : Enumerator for the focused state icon.
selected : Enumerator for the selected state icon.

Return value:
None.


GUI.SetWindowStateTextures

Set the textures to display on customisable controls for each of its states. The textures are drawn piece meal so we need three for each - one for the left hand end, one for the right hand end and one for the body of the window -
between the two ends.

Each page area is passed as a four integers forming a rectangle - such that 'n_l_t' is the top part of the page area for the left hand side for the neutral state.

prototype GUI.SetWindowStateTextures( hwindow customisable_window,
                     string texture_request,
                     int n_l_l, int n_l_t, int n_l_r, int n_l_b,
                     int n_b_l, int n_b_t, int n_b_r, int n_b_b,
                     int n_r_l, int n_r_t, int n_r_r, int n_r_b,
                     int f_l_l, int f_l_t, int f_l_r, int f_l_b,
                     int f_b_l, int f_b_t, int f_b_r, int f_b_b,
                     int f_r_l, int f_r_t, int f_r_r, int f_r_b,
                     int s_l_l, int s_l_t, int s_l_r, int s_l_b,
                         int s_b_l, int s_b_t, int s_b_r, int s_b_b,
                     int s_r_l, int s_r_t, int s_r_r, int s_r_b );

Parameters:
customisable_window: The window to set the texture for.
texture_request: The resource request for the texture page.

n_l_l : Coordinate for neutral state, left section, left coordinate.
n_l_t : Coordinate for neutral state, left section, top coordinate.
n_l_r : Coordinate for neutral state, left section, right coordinate.
n_l_b : Coordinate for neutral state, left section, bottom coordinate.

n_b_l : Coordinate for neutral state, body section, left coordinate.
n_b_t : Coordinate for neutral state, body section, top coordinate.
n_b_r : Coordinate for neutral state, body section, right coordinate.
n_b_b : Coordinate for neutral state, body section, bottom coordinate.

n_r_l : Coordinate for neutral state, right section, left coordinate.
n_r_t : Coordinate for neutral state, right section, top coordinate.
n_r_r : Coordinate for neutral state, right section, right coordinate.
n_r_b : Coordinate for neutral state, right section, bottom coordinate.

f_l_l : Coordinate for focused state, left section, left coordinate.
f_l_t : Coordinate for focused state, left section, top coordinate.
f_l_r : Coordinate for focused state, left section, right coordinate.
f_l_b : Coordinate for focused state, left section, bottom coordinate.

f_b_l : Coordinate for focused state, body section, left coordinate.
f_b_t : Coordinate for focused state, body section, top coordinate.
f_b_r : Coordinate for focused state, body section, right coordinate.
f_b_b : Coordinate for focused state, body section, bottom coordinate.

f_r_l : Coordinate for focused state, right section, left coordinate.
f_r_t : Coordinate for focused state, right section, top coordinate.
f_r_r : Coordinate for focused state, right section, right coordinate.
f_r_b : Coordinate for focused state, right section, bottom coordinate.

s_l_l : Coordinate for selected state, left section, left coordinate.
s_l_t : Coordinate for selected state, left section, top coordinate.
s_l_r : Coordinate for selected state, left section, right coordinate.
s_l_b : Coordinate for selected state, left section, bottom coordinate.

s_b_l : Coordinate for selected state, body section, left coordinate.
s_b_t : Coordinate for selected state, body section, top coordinate.
s_b_r : Coordinate for selected state, body section, right coordinate.
s_b_b : Coordinate for selected state, body section, bottom coordinate.

s_r_l : Coordinate for selected state, right section, left coordinate.
s_r_t : Coordinate for selected state, right section, top coordinate.
s_r_r : Coordinate for selected state, right section, right coordinate.
s_r_b : Coordinate for selected state, right section, bottom coordinate.

Return value:
None.


GUI.SetWindowTextFormatting

Set the window's text formatting - should the text be centred? If not, how much offset from the left of the canvas should there be?

prototype GUI.SetWindowTextFormatting( hwindow customisable_window,
                    bool centred,
                    int text_offset );

Parameters:
customisable_window : The window to format.
 centred : Boolean for centering on / off
text_offset : How much to offset the text from the left hand side of the canvas.

Return value:
None.


GUI.SetWindowTitle

Set the title for a given window.

prototype GUI.SetWindowTitle( hwindow window, string title );

Parameters:
window : The window to set the title for.
title : String containing the title.

Return value:
None.

See Also:
 WindowTitle


GUI.CancelFocusLock

Cancel any current focus locking.

prototype GUI.CancelFocusLock();

Parameters:
None.

Return value:
None.


GUI.OnControlFocusCancel

Generate an input message for control focus cancel.

prototype GUI.OnControlFocusCancel( hwindow window );

Parameters:
window : The window to set the control focus for.

Return value:
None.

See also:
OnControlFocusDown, OnControlFocusLeft, OnControlFocusRight, OnControlFocusSelect, OnControlFocusUp


GUI.OnControlFocusDown

Generate an input message for control focus down

prototype GUI.OnControlFocusDown( hwindow window );

Parameters:
window : The window to set the control focus for.

Return value:
None.

See also:
OnControlFocusCancel, OnControlFocusLeft, OnControlFocusRight, OnControlFocusSelect, OnControlFocusUp


GUI.OnControlFocusLeft

Generate an input message for control focus left.

prototype GUI.OnControlFocusLeft( hwindow window );

Parameters:
window : The window to set the control focus for.

Return value:
None.

See also:
OnControlFocusCancel, OnControlFocusDown, OnControlFocusRight, OnControlFocusSelect, OnControlFocusUp


GUI.OnControlFocusRight

Generate an input message for control focus right.

prototype GUI.OnControlFocusRight( hwindow window );

Parameters:
window : The window to set the control focus for.

Return value:
None.

See also:
OnControlFocusCancel, OnControlFocusDown, OnControlFocusLeft, OnControlFocusSelect, OnControlFocusUp


GUI.OnControlFocusSelect

Generate an input message for control focus select.

prototype GUI.OnControlFocusSelect( hwindow window );

Parameters:
window : The window to set the control focus for.

Return value:
None.

See also:
OnControlFocusCancel, OnControlFocusDown, OnControlFocusLeft, OnControlFocusRight, OnControlFocusUp


GUI.OnControlFocusUp

Generate an input message for control focus up

prototype GUI.OnControlFocusUp( hwindow window );

Parameters:
window : The window to set the control focus for.

Return value:
None.

See also:
OnControlFocusCancel, OnControlFocusDown, OnControlFocusLeft, OnControlFocusRight, OnControlFocusSelect


GUI.SetControlFocusCancelFunction

If the control focus 'Cancel' is performed at a level where no windows above the focused one will accept the control focus then this function is called instead.

prototype GUI.SetControlFocusCancelFunction( string function );

Parameters:
function : The function to call..

Return value:
None.


GUI.SetFirstControlFocus

Set the first control focus - i.e. the window to select if no windows are selected.

prototype GUI.SetFirstControlFocus( hwindow first_focus );

Parameters:
first_focus : The window to select.

Return value:
None.


GUI.SetFocus

Used to manually set the focus to the given window

prototype GUI.SetFocus( hwindow focus );

Parameters:
focus : The window to focus on..

Return value:
None.


GUI.SetInputOverrideFunctions

Set functions overriding the normal window behaviour in the situation of the various control focus commands being given.

prototype GUI.SetInputOverrideFunctions(
    hwindow window,
    string cf_left,
    string cf_up,
    string cf_right,
    string cf_down,
    string cf_select,
    string cf_cancel,
    string mouse_down,
    string mouse_up,
    string mouse_down_held );

Parameters:
cf_left : Function to call on control focus left.
cf_up : Function to call on control focus up.
cf_right : Function to call on control focus right
cf_down : Function to call on control focus down.
cf_select : Function to call on control focus select.
cf_cancel: Function to call on control focus cancel.
mouse_down : Function to call on mouse down.
mouse_up : Function to call on mouse up.
mouse_down_held : Function to call on mouse held down.

Return value:
None.


GUI.SetWindowAcceptFocus

Set whether a window will accept focus or not.

prototype GUI.SetWindowAcceptFocus( hwindow window, bool accept );

Parameters:
window : The window to set the focus accept.
accept : Boolean setting for focus accept.

Return value:
None.


GUI.SetWindowNextFocus

Set the window that the control focus will be shifted to if the focus is shifted to the next window.

prototype GUI.SetWindowNextFocus( hwindow window, hwindow focus );

Parameters:
window : The window to set the next focus for.
focus : The next window to focus.

Return value:
None.


GUI.SetWindowPreviousFocus

Set the window that the control focus will be shifted to if the focus is shifted to the next window.

prototype GUI.SetWindowPreviousFocus( hwindow window, hwindow focus );

Parameters:
window : The window to set the previous focus for.
focus : The previous window to focus.

Return value:
None.


GUI.WindowNextFocus

Get the next focus.

prototype hwindow GUI.WindowNextFocus( hwindow window );

Parameters:
window : The window to get the next focus from.

Return value:
The handle of the next focus window


GUI.WindowPreviousFocus

Get the previous focus.

prototype hwindow GUI.WindowPreviousFocus( hwindow window );

Parameters:
window : The window to get the previous focus from.

Return value:
The handle of the previous focus window


GUI.CreateEditBox

Create a 'text window' GUI element, with it's top-left hand corner in the given position, with the given width and height (all in frame units) and with the given parent. The sixth parameter determines whether or not the edit box should be multi-line. The final argument sets the box's default text. The seventh determines whether the edit box will only accept characters in [0-9]

prototype hwindow GUI.CreateEditBox( int x, int y,
                     int width, int height,
                     hwindow parent,
                     bool multi_line,
                        string default_text,
                     bool numeric );

Parameters:
x : The x coordinate of the top left hand corner of the window in it's parent's canvas.
y : The y coordinate of the top left hand corner of the window in it's parent's canvas.
width : The width of the window.
height : The height of the window.
parent : The window to add the new window to as a child.
multi_line : Determines if the edit box it multi-line.
default_text : Specifies the default text initially displayed in the edit box.
numeric : Determines whether the edit box will only accept characters in [0-9].

Return value:
A handle to the new edit box, or a null handle if there was an error.

See also:
EditBoxValue, SetEditBoxCursorToEnd, SetEditBoxMaxCharLength, SetEditBoxOverrides, SetEditBoxValue


GUI.EditBoxValue

Set the value entered into the given edit box.

prototype string GUI.EditBoxValue( hwindow edit_box );

Parameters:
edit_box : The edit box to query.

Return value:
The value of the edit box.

See also:
GUI.CreateEditBox, SetEditBoxCursorToEnd, SetEditBoxMaxCharLength, SetEditBoxOverrides, SetEditBoxValue


GUI.SetEditBoxCursorToEnd

Set the edit box cursor to the end.

prototype GUI.SetEditBoxCursorToEnd( hwindow edit_box );

Parameters:
edit_box : The edit box to query.

Return value:
None.

See also:
GUI.CreateEditBox, EditBoxValue, SetEditBoxMaxCharLength, SetEditBoxOverrides, SetEditBoxValue


GUI.SetEditBoxMaxCharLength

Set the maximum number of characters allowed in a single line edit box.

prototype GUI.SetEditBoxMaxCharLength( hwindow edit_box, int length );

Parameters:
edit_box : The edit box to query.
length : The maximum number of characters allowed..

Return value:
None.

See also:
GUI.CreateEditBox, EditBoxValue, SetEditBoxCursorToEnd, SetEditBoxOverrides, SetEditBoxValue


GUI.SetEditBoxOverrides

Set optional Pog functions to be called when editing begins, is cancelled or is finished

prototype GUI.SetEditBoxOverrides( hwindow edit_box,
                   string start_editing,
                   string cancel_editing,
                   string finish_editing );

Parameters:
edit_box : The edit box to query.
start_editing : The function to call when starting editing.
cancel_editing : The function to call when canelling editing.
finish_editing : The function to call when finishing editing.

Return value:
None.

See also:
GUI.CreateEditBox, EditBoxValue, SetEditBoxCursorToEnd,


GUI.SetEditBoxValue

Set the value entered into the given edit box.

prototype string GUI.SetEditBoxValue( hwindow edit_box, string text );

Parameters:
edit_box : The edit box to query.
text : The text value to set for the edit box.

Return value:
The value of the edit box.

See also:
GUI.CreateEditBox.


GUI.AddComboBoxEntry

Add an entry to the given combo box.

prototype GUI.AddComboBoxEntry( hwindow combo_box,
                                string entry );

Parameters:
combo_box : The combo box to initialise.
entry : The entry to add.

Return value:
None.

See also:
GUI.CreateComboBox, GUI.ComboBoxValue, GUI.ComboBoxValueIndex.


GUI.ComboBoxValue

Get the value entered into the given combo box.

prototype string GUI.ComboBoxValue( hwindow combo_box );

Parameters:
combo_box : The combo box to query.

Return value:
The current value of the combo box - the text in the edit box portion of the window.

See also:
GUI.CreateComboBox, GUI.AddComboBoxEntry, GUI.ComboBoxValueIndex.


GUI.ComboBoxValueIndex

Get the index of the selected value of the combo box.

prototype int GUI.ComboBoxValueIndex( hwindow combo_box );

Parameters:
combo_box : The combo box to query.

Return value:
The index of the currently selected value of the combo box or -1 if no entry is selected or if the combo box is editable.

Notes:
This function only work with non-editable combo boxes.

It returns the index into the entries of the combo box that is currently selected and being displayed in the edit box portion of the combo box.

See also:
GUI.CreateComboBox, GUI.AddComboBoxEntry, GUI.ComboBoxValue.


GUI.CreateComboBox

Create a 'combo box' GUI element, with it's top-left hand corner in the given position, with the given width and height (all in frame units) and with the given parent. The sixth parameter determines whether or not the edit box portion of the combo box is editable. The final parameter is the default value to put in the edit box portion of the box.

prototype hwindow GUI.CreateComboBox( int x,
                                      int y,
                                      int width,
                                      int height,
                                      hwindow parent,
                                      bool editable,
                                      string default_value );

Parameters:
x : The x coordinate of the top left hand corner of the window in it's parent's canvas.
y : The y coordinate of the top left hand corner of the window in it's parent's canvas.
width : The width of the window.
height : The height of the window.
parent : The window to add the new window to as a child.
editable : Is the edit box portion of the box editable?
default_value : The default value for the edit box portion of the combo box.

Return value:
A handle to the new combo box, or null if an error occured.

Notes:
A combo box is an edit box combined with a drop down list box.

The new combo box has no entries in the drop down list box after creation. These have to be manually added.

See also:
GUI.AddComboBoxEntry, GUI.ComboBoxValue, GUI.ComboBoxValueIndex.


GUI.AddListBoxEntry

Adds the given entry (that is to say, window) to a list box.

prototype GUI.AddListBoxEntry( hwindow list_box,
                               hwindow entry );

Parameters:
list_box : A list box to add an entry to.
entry : The entry to add - a window handle.

Return value:
None.

See also:
CancelListBoxSelection, CreateListBox, DisableHighlight, ListBoxFocusedEntry, ListBoxSelectedIndex, ListBoxValue, RemoveListBoxEntries, RemoveListBoxEntry, SelectListBoxEntry, SetListBoxFocusedEntry, SetListBoxGap, SetListBoxSelectFunction


GUI.CancelListBoxSelection

Cancel any selections in a list box.Type your question here and then click Search

prototype GUI.CancelListBoxSelection( hwindow list_box );

Parameters:
list_box : The list box to reset.

Return value:
None.

Notes:
If the list box is multiple selection then all selection entries are set to unselected.

See also:
AddListBoxEntry , CreateListBox, DisableHighlight, ListBoxFocusedEntry, ListBoxSelectedIndex, ListBoxValue, RemoveListBoxEntries, RemoveListBoxEntry, SelectListBoxEntry, SetListBoxFocusedEntry, SetListBoxGap, SetListBoxSelectFunction


GUI.CreateListBox

Create a 'list box' GUI element, with it's top-left hand corner in the given position, with the given width and height (all in frame units) and with the given parent. The sixth parameter determines whether or not the list box is selectable, which overrides the seventh parameter which determines whether or not more than one entry in the box can be selected at once.

prototype hwindow GUI.CreateListBox( int x, int y,
                     int width, int height,
                     hwindow parent,
                        bool selectable,
                     bool multiple_selection );

Parameters:
x : The x coordinate of the top left hand corner of the window in it's parent's canvas.
y : The y coordinate of the top left hand corner of the window in it's parent's canvas.
width : The width of the window.
height : The height of the window.
parent : The window to add the new window to as a child.
selectable : Is this list box to be selectable?
multiple_selection : Is it possible to select more than one entry of this list box.

Return value:
A handle to the new list box, or null if there has been an error.

Notes:
This function creates an empty list box. The entries have to added separately.

See also:
AddListBoxEntry , CancelListBoxSelection, DisableHighlight, ListBoxFocusedEntry, ListBoxSelectedIndex, ListBoxValue, RemoveListBoxEntries, RemoveListBoxEntry, SelectListBoxEntry, SetListBoxFocusedEntry, SetListBoxGap, SetListBoxSelectFunction


GUI.DisableHighlight

Disable the orange highlight added by default by list boxes

prototype GUI.DisableHighlight( hwindow list_box );

Parameters:
list_box : The list box to operate on.

Return value:
None.

See also:
AddListBoxEntry , CancelListBoxSelection, CreateListBox, ListBoxFocusedEntry, ListBoxSelectedIndex, ListBoxValue, RemoveListBoxEntries, RemoveListBoxEntry, SelectListBoxEntry, SetListBoxFocusedEntry, SetListBoxGap, SetListBoxSelectFunction


GUI.ListBoxFocusedEntry

Which list box entry is being selected?

prototype int GUI.ListBoxFocusedEntry( hwindow list_box );

Parameters:
list_box : The list box to operate on.
index : The index into the list box entries to select.

Return value:
The index of the currently focused entry, as an int. -1 is returned if no entry is selected.

See also:
AddListBoxEntry , CancelListBoxSelection, CreateListBox, DisableHighlight, ListBoxSelectedIndex, ListBoxValue, RemoveListBoxEntries, RemoveListBoxEntry, SelectListBoxEntry, SetListBoxFocusedEntry, SetListBoxGap, SetListBoxSelectFunction


GUI.ListBoxSelectedIndex

Get the (zero based) index of the selected value in the list box. If it is a multiple selection box then it returns the first. If there is no selection then return -1.

prototype int GUI.ListBoxSelectedIndex( hwindow list_box );

Parameters:
list_box : The list box to query.

Return value:
The index of the selected entry in a list box. If no entry is selected then -1 is returned. If the list box is a multiple selection box then the index of the first entry is returned.

Notes:
By 'index' we mean the index into the list of entries in the list box, starting from 0.

See also:
AddListBoxEntry , CancelListBoxSelection, CreateListBox, DisableHighlight, ListBoxFocusedEntry, ListBoxValue, RemoveListBoxEntries, RemoveListBoxEntry, SelectListBoxEntry, SetListBoxFocusedEntry, SetListBoxGap, SetListBoxSelectFunction


GUI.ListBoxValue

Get the selected value in the given list box. If it is a multiple selection box then it returns the first. If there is no selection then return a null handle.

prototype hwindow GUI.ListBoxValue( hwindow list_box );

Parameters:
list_box : The list box to query.

Return value:
The selected list box entry, or an empty string if there is no entry selected. If the list box is a multiple selection box then the first selected entry will be returned.

Note that the list box entries are windows in their own right.

See also:
AddListBoxEntry , CancelListBoxSelection, CreateListBox, DisableHighlight, ListBoxFocusedEntry, ListBoxSelectedIndex, RemoveListBoxEntries, RemoveListBoxEntry, SelectListBoxEntry, SetListBoxFocusedEntry, SetListBoxGap, SetListBoxSelectFunction


GUI.ListBoxValueIndex

Get the index into the entries of a list box of the selected entry.

prototype int GUI.ListBoxValueIndex( hwindow list_box );

Parameters:
list_box : The list box to query.

Return value:
The index of the selected entry in a list box. If no entry is selected then -1 is returned. If the list box is a multiple selection box then the index of the first entry is returned.

Notes:
By 'index' we mean the index into the list of entries in the list box, starting from 0.

See also:
GUI.CreateListBox, GUI.AddListBoxEntry, GUI.ListBoxValue, GUI.RemoveListBoxEntries, GUI.CancelListBoXSelection, GUI.SetListBoXEntry.


GUI.RemoveListBoxEntries

Remove all the entries of a list box.

prototype GUI.RemoveListBoxEntries( hwindow list_box );

Parameters:
list_box : The list box to reset.

Return value:
None.

See also:
AddListBoxEntry , CancelListBoxSelection, CreateListBox, DisableHighlight, ListBoxFocusedEntry, ListBoxSelectedIndex, ListBoxValue, RemoveListBoxEntry, SelectListBoxEntry, SetListBoxFocusedEntry, SetListBoxGap, SetListBoxSelectFunction


GUI.RemoveListBoxEntry

// Remove the given list box entry and return the now parentless window

prototype hwindow GUI.RemoveListBoxEntry( hwindow list_box, int index );

Parameters:
list_box : The list box to reset.
index : The index of the entry to remove.

Return value:
None.

See also:
GUI.CreateListBox, GUI.AddListBoxEntry, GUI.ListBoxValue, GUI.ListBoxSelectedIndex, GUI.CancelListBoxSelection, GUI. SelectListBoxEntry.


GUI.SelectListBoxEntry

Make the list box entry at the given index selected.

prototype GUI.SelectListBoxEntry( hwindow list_box, int index );

Parameters:
list_box : The list box to operate on.
index : The index into the list box entries to select.

Return value:
None.

Notes:
This function will make selected the entry in the list box indicated by the given index.

It is safe to select an already selected entry.

Unless the box is a multiple select list box, selecting an entry will cancel any other selected entries.

See also:
AddListBoxEntry, CancelListBoxSelection, CreateListBox, DisableHighlight, ListBoxFocusedEntry, ListBoxSelectedIndex, ListBoxValue, RemoveListBoxEntries, RemoveListBoxEntry, SetListBoxFocusedEntry, SetListBoxGap, SetListBoxSelectFunction


GUI.SetListBoxFocusedEntry

Set the list box focused entry.

prototype GUI.SetListBoxFocusedEntry( hwindow list_box int entry );

Parameters:
list_box : The list box to operate on.
entry : The index into the list box entries to select.

Return value:
None

See also:
AddListBoxEntry , CancelListBoxSelection, CreateListBox, DisableHighlight, ListBoxFocusedEntry, ListBoxSelectedIndex, ListBoxValue, RemoveListBoxEntries, RemoveListBoxEntry, SelectListBoxEntry, SetListBoxGap, SetListBoxSelectFunction


GUI.SetListBoxGap

Set the vertical spacing between list box elements.

prototype GUI.SetListBoxGap( hwindow list_box, int gap );

Parameters:
list_box : The list box to operate on.
gap : The gap between the list box entries.

Return value:
None.

See also:
AddListBoxEntry , CancelListBoxSelection, CreateListBox, DisableHighlight, ListBoxFocusedEntry, ListBoxSelectedIndex, ListBoxValue, RemoveListBoxEntries, RemoveListBoxEntry, SelectListBoxEntry, SetListBoxFocusedEntry, SetListBoxSelectFunction


GUI.SetListBoxSelectFunction

Set the given Pog function to get called when a list box entry is selected

prototype GUI.SetListBoxSelectFunction( hwindow list_box, string function );

Parameters:
list_box : The list box to operate on.
function : The function to use when the list box is selected.

Return value:
None

See also:
AddListBoxEntry , CancelListBoxSelection, CreateListBox, DisableHighlight, ListBoxFocusedEntry, ListBoxSelectedIndex, ListBoxValue, RemoveListBoxEntries, RemoveListBoxEntry, SelectListBoxEntry, SetListBoxFocusedEntry, SetListBoxGap


GUI.CreateDualScrollbars

Create a scrollbar GUI element - both horizontal and vertical.

prototype hwindow GUI.CreateDualScrollbars( hwindow target );

Parameters:
target : The window to attach the scrollbars to.

Return value:
A handle to the scrollbar GUI element, or a null handle if there was an error.

Notes:
The 'scrollbar' GUI element is a decorator. This means that it attaches to an existing window and cannot exist on its own.

When you attach a decorator to a window, the existing window becomes a child of the decorator rather than its previous parent. The decorator replaces the existing window as a child of the parent - the decorator 'pushes in' between the window and its parent.

There must be enough room in the canvas of the parent for the decorator to fit around the existing window. For example, if a window was in the far top left corner of its parent's canvas and was then decorated with a border there would not be enough room in the parent's canvas to fit the top and left portions of the border.

See also:
GUI.CreateBorder, GUI.CreateHorizontalScrollbar, GUI.CreateVerticalScrollbar, CreateHorizontalScrollbarDecorator, CreateVerticalScrollbarDecorator


GUI.CreateHorizontalScrollbar

Create a horizontal scrollbar GUI element.

prototype hwindow GUI.CreateHorizontalScrollbar( int x,
                                                 int y,
                                                 int width,
                                                 int height,
                                                 hwindow parent,
                                                 hwindow target );

Parameters:
x : The x coordinate of this window's desired offset into the parent's client area.

y : The y coordinate of this window's desired offset into the parent's client area.

width : The width of the window to create.

height : The height of the window to create.

target : The window to attach the scrollbar to.

Return value:
A handle to the scrollbar GUI element, or a null handle if there was an error.

Notes:
This function creates a stand-alone scrollbar, rather than a decorator enveloping the attached window.

See also:
CreateBorder, CreateDualScrollbars, CreateHorizontalScrollbarDecorator, CreateVerticalScrollbar, CreateVerticalScrollbarDecorator


GUI.CreateHorizontalScrollbarDecorator

Create a horizontal scrollbar around the given window.

prototype hwindow GUI.CreateHorizontalScrollbarDecorator( hwindow target );

Parameters:

target : The window to attach the scrollbar to.

Return value:
A handle to the scrollbar GUI element, or a null handle if there was an error.

Notes:
This function creates a decorator enveloping the attached window rather than a stand-alone scrollbar.

See also:
CreateBorder, CreateDualScrollbars, CreateHorizontalScrollbarDecorator, CreateVerticalScrollbar, CreateVerticalScrollbarDecorator


GUI.ReattachScrollbar

Change the window that a scrollbar is attached to.

prototype GUI.ReattachScrollbar( hwindow scrollbar, hwindow target );

Parameters:

scrollbar : The scrollbar to attach.
target : The window to attach the scrollbar to.

Return value:
None.

See also:
CreateBorder, CreateDualScrollbars, CreateHorizontalScrollbar, CreateHorizontalScrollbarDecorator, CreateVerticalScrollbar, CreateVerticalScrollbarDecorator


GUI.CreateVerticalScrollbar

Creates a vertical scrollbar at the given point of the given size, attached to the given target. We also pass in the ratio between scrollbar width and button length (to allow the new window to set it's clickable mouse areas correctly) and a hint to the avatar factory, which allows us to tailor the avatar used to draw the scrollbar.

prototype hwindow GUI.CreateVerticalScrollbar( int x, int y,
                           int width, int height,
                           hwindow parent,
                           hwindow target,
                           float button_length_to_width_ratio,
                           string avatar_hint );

Parameters:
x : The x coordinate of this window's desired offset into the parent's client area.
y : The y coordinate of this window's desired offset into the parent's client area.
width : The width of the window to create.
height : The height of the window to create.
target : The window to attach the scrollbar to.
button_length_to_width_ratio :Ratio between button length to width.
avatar_hint : Hint to the avatar factory.

Return value:
A handle to the scrollbar GUI element, or a null handle if there was an error.

Notes:
This function creates a stand-alone scrollbar, rather than a decorator enveloping the attached window.

See also:
CreateBorder, CreateDualScrollbars, CreateVerticalScrollbarDecorator, CreateHorizontalScrollbar, CreateHorizontalScrollbarDecorator


GUI.CreateVerticalScrollbarDecorator

Create a vertical scrollbar around the given window.

prototype hwindow GUI.CreateVerticalScrollbarDecorator( hwindow target );

Parameters:

target : The window to attach the scrollbar to.

Return value:
A handle to the scrollbar GUI element, or a null handle if there was an error.

Notes:
This function creates a decorator enveloping the attached window rather than a stand-alone scrollbar.

See also:
CreateBorder, CreateDualScrollbars, CreateHorizontalScrollbar, CreateHorizontalScrollbarDecorator, CreateVerticalScrollbar


GUI.CreateCheckbox

Create a 'checkbox' GUI element, with it's top-left hand corner in the given position, with the given width and height (all in frame units) and with the given parent.

prototype hwindow GUI.CreateCheckbox( int x,
                                      int y,
                                      int width,
                                      int height,
                                      hwindow parent,
                                      bool checked );

Parameters:
x : The x coordinate of the top left hand corner of the window in it's parent's canvas.
y : The y coordinate of the top left hand corner of the window in it's parent's canvas.
width : The width of the window.
height : The height of the window.
parent : The window to add the new window to as a child.
checked : Does the checkbox start checked?

Return value:
A handle to a new checkbox, or a null handle if there is an error.

See also:
GUI.CheckboxValue.


GUI.CheckboxValue

Determine whether or now a checkbox is checked.

prototype bool GUI.CheckboxValue( hwindow checkbox );

Parameters:
checkbox : The box to query.

Return value:
Returns true if the checkbox is checked, false otherwise.

See also:
GUI.CreateCheckbox.


GUI.CreateRadioButton

Create a 'radio button' GUI element, with it's top-left hand corner in the given position, with the given width and height (all in frame units) and with the given parent.

prototype hwindow GUI.CreateRadioButton( int x,
                                         int y,
                                         int width,
                                         int height,
                                         hwindow parent,
                                         bool checked );

Parameters:
x : The x coordinate of the top left hand corner of the window in it's parent's canvas.
y : The y coordinate of the top left hand corner of the window in it's parent's canvas.
width : The width of the window.
height : The height of the window.
parent : The window to add the new window to as a child.
checked : Does the radio button start checked?

Return value:
A handle to a new radio button, or a null handle if there is an error.

Notes:
Radio buttons are grouped with all other sibling radio buttons - i.e. buttons with the same parent. Only one of them can ever be selected.

See also:
GUI.RadioButtonValue, SetRadioButtonChecked


GUI.RadioButtonValue

Determine whether or now a radio button is checked.

prototype bool GUI.RadioButtonValue( hwindow button );

Parameters:
button : The button to query.

Return value:
Returns true if the button is checked, false otherwise.

See also:
GUI.CreateRadioButton.


GUI.SetRadioButtonChecked

Determine whether or now a radio button is checked.

prototype bool GUI.SetRadioButtonChecked( hwindow button, bool checked );

Parameters:
button : The button to query.
checked : Set the button on or off.

Return value:
None

See also:
GUI.CreateRadioButton, RadioButtonValue


GUI.CreateTextWindow

Create a 'text window' GUI element, with it's top-left hand corner in the given position, with the given width and height (all in frame units) and with the given parent.

prototype hwindow GUI.CreateTextWindow( int x,
                                        int y,
                                        int width,
                                        int height,
                                        hwindow parent );

Parameters:
x : The x coordinate of the top left hand corner of the window in it's parent's canvas.
y : The y coordinate of the top left hand corner of the window in it's parent's canvas.
width : The width of the window.
height : The height of the window.
parent : The window to add the new window to as a child.

Return value:
A handle to a new text window, or a null handle if an error occured.

Notes:
This function creates a window without any text in it. It can be initialised with either an HTML string or an HTML resource.

See also:
SetTextWindowString, SetTextWindowResource.


GUI.SetTextWindowResource

Sets the text contained in a text window to the string found in the given resource.

prototype GUI.SetTextWindowResource( hwindow text_window,
                                     string resource );

Parameters:
text_window : The window to initialise or reset.
resource : A resource request for an HTML file.

Return value:
None.

Notes:
The resource passed into this functions should be in HTML.

See also:
CreateTextWindow, SetTextWindowString.


GUI.SetTextWindowString

Sets the text contained in a text window to the given string.

prototype GUI.SetTextWindowString( hwindow text_window,
                                   string text );

Parameters:
text_window : The window to initialise or reset.
text : The text to set in the window in HTML.

Return value:
None.

Notes:
The string passed into this functions should be an HTML string, but a string with no HTML tags is equally acceptible.

See also:
GUI.CreateTextWindow, GUI.SetTextWindowResource.


GUI.TextWindowBack

Shifts the text window to show the previous HTML page

prototype bool GUI.TextWindowBack( hwindow text_window );

Parameters:
text_window : The window which you want to go back.

Return value:
None.

See also:
GUI.CreateTextWindow


GUI.CreateSliderControl

Create a slider control.

GUI.CreateSliderControl( int x,
               int y,
             int width,
             int height,
             hwindow parent,
             float start_value,
             float end_value,
             float step_value )

Parameters:
x : The x coordinate of the top left hand corner of the window in it's parent's canvas.
y : The y coordinate of the top left hand corner of the window in it's parent's canvas.
width : The width of the window.
height : The height of the window.
parent : The window to add the new window to as a child.
start_value : The minimum value of the slider.
end_value : The maximum value of the slider.
step_value : The number of steps the slider has between its min and max values.

Return value:
None

See also:
SliderControlValue, SetSliderControlValue


GUI.CreateSplitterWindow

Creates a splitter window - that is a window which contains two other windows, with a horizontal line between them. The split parameter sets how far down the canvas of the window the split is placed.

prototype hwindow GUI.CreateSplitterWindow( int x,
                                        int y,
                                        int width,
                                        int height,
                                        hwindow parent,
                    int split,
                    bool fancy );

Parameters:
x : The x coordinate of the top left hand corner of the window in it's parent's canvas.
y : The y coordinate of the top left hand corner of the window in it's parent's canvas.
width : The width of the window.
height : The height of the window.
parent : The window to add the new window to as a child.
split : How far down the screen the split is.
fancy : Specify fancy / non fancy border.

Return value:
A handle to a new text window, or a null handle if an error occured.

See also:
CreateFancySplitterWindow, SplitterWindowBottomWindow, SplitterWindowTopWindow


GUI.SplitterWindowBottomWindow

Gets the bottom of the two windows contained in a splitter window.

prototype hwindow GUI.SplitterWindowBottomWindow( hwindow window );

Parameters:
window : The window to get the bottom window from.

Return value:
A handle to the window, or a null handle if an error occured.

See also:
CreateFancySplitterWindow, CreateSplitterWindow, SplitterWindowTopWindow


GUI.SplitterWindowTopWindow

Gets the top of the two windows contained in a splitter window.

prototype hwindow GUI.SplitterWindowTopWindow( hwindow window );

Parameters:
window : The window to get the top window from.

Return value:
A handle to a new text window, or a null handle if an error occured.

See also:
CreateFancySplitterWindow, CreateSplitterWindow, SplitterWindowBottomWindow


GUI.SetShadyBarWidth

Set the shady bar width.

prototype GUI.SetShadyBarWidth( int width );

Parameters:
width : The width of the shady bar.

Return value:
None.

See also:
SetRHSShadyBarWidth


GUI.SetRHSShadyBarWidth

Set the right hand side shady bar width.

prototype GUI.SetRHSShadyBarWidth( int width );

Parameters:
width : The width of the right hand side shady bar.

Return value:
None.

See also:
SetShadyBarWidth


GUI.CreateSliderControl

Create a slider control.

prototype hwindow GUI.CreateSliderControl( int x, int y,
                       int width, int height,
                       hwindow parent,
                       float start_value,
                       float end_value,
                       float step_value );

Parameters:
x  : x coordinate of window position.
y  : y coordinate of window position.
parent  : The handle to the parent window.
start_value  : The minimum value of the slider.
end_value : The maximum value of the slider.
step_value : The number of steps in the slider scale.

Return value:
The handle to the window.

See also:
SliderControlValue, SetSliderControlValue


GUI.SliderControlValue

Get the value of the slider.

prototype float GUI.GetSliderControlValue( hwindow slider_control );

Parameters:
slider_control  : The handle to the slider window.

Return value:
The value of the slider as a float.

See also:
CreateSliderControl, SetSliderControlValue


GUI.SetSliderControlValue

Set the value of the slider.

prototype GUI.SetSliderControlValue( hwindow slider_window, float value );

Parameters:
slider_control  : The handle to the slider window.
value : The value to set.

Return value:
None

See also:
CreateSliderControl, SliderControlValue


GUI.RegisterSound

Set a sound for a class of GUI event.

prototype GUI.RegisterSound( string sound_request, eSound sound );

Parameters:
sound_request: The resource string for the sound file.
sound: Enum specifiying the GUI event class.

Return value:
None.

See Also:
QueueSound, PlaySound, StartSound, StopSound, SetBeepOnGainFocus


GUI.QueueSound

Play a GUI audio cue next frame.

prototype GUI.QueueSound( eSound sound );

Parameters:
sound: Enum specifiying the sound class.

Return value:
None.

See Also:
RegisterSound, PlaySound, StartSound, StopSound, SetBeepOnGainFocus


GUI.PlaySound

Play a GUI audio sound immediately.

prototype GUI.QueueSound( eSound sound );

Parameters:
sound: Enum specifiying the sound class.

Return value:
None.

Notes:

The GUI audio queue is purged if this command is used.

See Also:
RegisterSound, QueueSound, StartSound, StopSound, SetBeepOnGainFocus


GUI.StartSound

Start a GUI looping sound.

prototype GUI.StartSound( eSound sound );

Parameters:
sound : Enum specifiying the sound class.

Return value:
None.

See Also:


GUI.StartSound

Stop any GUI looping sound.

prototype GUI.StopSound( eSound sound );

Parameters:
sound : Enum specifiying the sound class.

Return value:
None.

See Also:
RegisterSound, QueueSound, PlaySound, SetBeepOnGainFocus


GUI.SetBeepOnGainFocus

Set a window to beep when it gains focus.

prototype GUI.SetBeepOnGainFocus( bool beep );

Parameters:
beep : Boolean to determine if the window beeps or not.

Return value:
None.

See Also:
RegisterSound, QueueSound, PlaySound, StartSound, StopSound


GUI.PlayBackgroundMovie

Plays a spinning movie in the background of the gui, with vertically scrolling text.

prototype GUI.PlayBackgroundMovie(string movie, string text);

Parameters:
movie : The URL of the movie
text : The URL of the text.

Return value:
None

Notes:
Text must be in the game's basic html format.

See also:
StopAllMovies, StopBackgroundMovie


GUI.StopAllMovies

Stop all movie playback.

prototype GUI.StopAllMovies();

Parameters:
None

Return value:
None

See also:
 PlayBackgroundMovie, StopBackgroundMovie


GUI.StopBackgroundMovie

Stop the background movie.

prototype GUI.StopBackgroundMovie();

Parameters:
None

Return value:
None

See also:


INIFile

Provides configuration INI file support for data stored by sections and keys.

Type definitions:

  • hinifile

Functions:

  • Cast
  • Create
  • Destroy
  • Exists
  • Float
  • Int
  • NumberedExists
  • NumberedFloat
  • NumberedString
  • NumberedInt
  • NumberedVectorX
  • NumberedVectorY
  • NumberedVectorZ
  • String
  • VectorX
  • VectorY
  • VectorZ

Notes:

All INIFiles that are created must also be destroyed, otherwise a memory leak occurs.


INIFile.hinifile

A handle to an INIFile object.

hinifile : hobject;


INIFile.Cast

Casts a handle to an object to a handle to an INI file.

prototype hgroup INIFile.Cast( hobject handle );

Parameters:
handle : The object handle to cast to the INI file handle.

Return value:
Returns a handle to a INI file or none if the cast was unsuccessful.


INIFile.Create

Creates an INIFile object.

prototype hinifile INIFile.Create( string filename );

Parameters:
filename : The filename of the INI file. The extension should not be added.

Return value:
Returns a handle to the INIFile object that was created, or none if the file was not found, could not be opened or read.

Notes:
Any INIFile objects created should also be destroyed, this is done by handing the returned handle to the destroy function.

See also:
INIFile.Destroy.


INIFile.Destroy

Destroy an INIFile object.

prototype INIFile.Destroy( hinifile handle );

Parameters:
handle : handle to the INIFile object.

Return value:
none.

Notes:
All INIFile objects that are created must be destroyed.

See also:
INIFile.Create.


INIFile.Exists

Test for the existence of the section and key in the INIFile object.

prototype bool INIFile.Exists( hinifile handle,
                               string section,
                               string key );

Parameters:
handle : The handle to the INIFile object
section : The section in the INIFile.
key : The key in the section.

Return value:
Returns a boolean indicating existence of section and key

See also:
INIFile.NumberedExists.


INIFile.Float

Access a float in the INIFile object under section and key

prototype float INIFile.Float( hinifile handle,
                             string section,
                             string key,
                             float default );

Parameters:
handle : The handle to the INIFile object
section : The section in the INIFile.
key : The key in to the section.
default : The default to return if the data does not exist.

Return value:
Returns the float stored at the section and key, or the default float.

Notes:
The default float will be returned if the section or key does not exist.

See also:
INIFile.String, INIFile.NumberedString, INIFile.Int, INIFile.NumberedInt, INIFile.NumberedFloat.


INIFile.Int

Access an int in the INIFile object under section and key

prototype int INIFile.Int( hinifile handle,
                           string section,
                           string key,
                           int default );

Parameters:
handle : The handle to the INIFile object
section : The section in the INIFile.
key : The key in to the section.
default : The default to return if the data does not exist.

Return value:
Returns the int stored at the section and key, or the default int.

Notes:
The default int will be returned if the section or key does not exist.

See also:
INIFile.String, INIFile.NumberedString, INIFile.NumberedInt, INIFile.Float, INIFile.NumberedFloat.


INIFile.NumberedExists

Test for the existence of the section and numbered key in the INIFile object.

prototype bool INIFile.NumberedExists( hinifile handle,
                                       string section,
                                       string key,
                                       int number );

Parameters:
handle : The handle to the INIFile object
section : The section in the INIFile.
key : The key in the section.
number : The number to append to the key.

Return value:
Returns a boolean indicating existence of section and numbered key

See also:
INIFile.Exists.


INIFile.NumberedFloat

Access a float in the INIFile object under section and numbered key

prototype float INIFile.NumberedFloat( hinifile handle,
                                       string section,
                                       string key,
                       int number,
                                       float default );

Parameters:
handle : The handle to the INIFile object
section : The section in the INIFile.
key : The key in to the section.
number : The number to append to the key.
default : The default to return if the data does not exist.

Return value:
Returns the float stored at the section and numbered key, or the default float.

Notes:
The default float will be returned if the section or numbered key does not exist.

See also:
INIFile.String, INIFile.NumberedString, INIFile.Int, INIFile.NumberedInt, INIFile.Float.


INIFile.NumberedInt

Access an int in the INIFile object under section and numbered key

prototype int INIFile.NumberedInt( hinifile handle,
                           string section,
                           string key,
                           int number,
                           int default );

Parameters:
handle : The handle to the INIFile object
section : The section in the INIFile.
key : The key in to the section.
number : The number to append to the key.
default : The default to return if the data does not exist.

Return value:
Returns the int stored at the section and numbered key, or the default int.

Notes:
The default int will be returned if the section or numbered key does not exist.

See also:
INIFile.String, INIFile.NumberedString, INIFile.Int, INIFile.Float, INIFile.NumberedFloat.


INIFile.NumberedString

Access a numbered string in the INIFile object under section and numbered key

prototype string INIFile.NumberedString( hinifile handle,
                                         string section,
                                         string key,
                                         int number,
                                         string default );

Parameters:
handle : The handle to the INIFile object.
section : The section in the INIFile.
key : The key in to the section.
number : The number that is appeneded to the key.
default : The default to return if the data does not exist.

Return value:
Returns the string stored at the section and numbered key, or the default string.

Notes:
The default string will be returned if the section or numbered key does not exist.

See also:
INIFile.String, INIFile.Int, INIFile.NumberedInt, INIFile.Float, INIFile.NumberedFloat.


INIFile.NumberedVectorX

Access the x component of the vector in the INIFile object under section and numbered key.

prototype float INIFile.NumberedVectorX( hinifile handle,
                                         string section,
                                         string key,
                                         int number );

Parameters:
handle : The handle to the INIFile object
section : The section in the INIFile.
key : The key in to the section.
number : The number to append to the key.

Return value:
Returns the float stored at the section and numbered key, or 0.

Notes:
0 will be returned if the section or numbered key does not exist.

See also:
INIFile.VectorX, INIFile.VectorY, INIFile.VectorZ, INIFile.NumberedVectorY, INIFile.NumberedVectorZ.


INIFile.NumberedVectorY

Access the y component of the vector in the INIFile object under section and numbered key.

prototype float INIFile.NumberedVectorY( hinifile handle,
                                         string section,
                                         string key,
                                         int number );

Parameters:
handle : The handle to the INIFile object
section : The section in the INIFile.
key : The key in to the section.
number : The number to append to the key.

Return value:
Returns the float stored at the section and numbered key, or 0.

Notes:
0 will be returned if the section or numbered key does not exist.

See also:
INIFile.VectorX, INIFile.VectorY, INIFile.VectorZ, INIFile.NumberedVectorX, INIFile.NumberedVectorZ.


INIFile.NumberedVectorZ

Access the z component of the vector in the INIFile object under section and numbered key.

prototype float INIFile.NumberedVectorZ( hinifile handle,
                                         string section,
                                         string key,
                                         int number );

Parameters:
handle : The handle to the INIFile object
section : The section in the INIFile.
key : The key in to the section.
number : The number to append to the key.

Return value:
Returns the float stored at the section and numbered key, or 0.

Notes:
0 will be returned if the section or numbered key does not exist.

See also:
INIFile.VectorX, INIFile.VectorY, INIFile.VectorZ, INIFile.NumberedVectorX, INIFile.NumberedVectorY.


INIFile.String

Access a string in the INIFile object under section and key

prototype string INIFile.String( hinifile handle,
                                 string section,
                                 string key,
                                 string default );

Parameters:
handle : The handle of the INIFile object.
section : The section in the INIFile.
key : The key in to the section.
default : The default to return if the data does not exist.

Return value:
Returns the string stored at the section and key, or the default string.

Notes:
The default string will be returned if the section or key does not exist.

See also:
INIFile.NumberedString, INIFile.Int, INIFile.NumberedInt, INIFile.Float, INIFile.NumberedFloat.


INIFile.VectorX

Access the x component of a vector in the INIFile object under section and key.

prototype float INIFile.VectorX( hinifile handle,
                                 string section,
                                 string key );

Parameters:
handle : The handle to the INIFile object
section : The section in the INIFile.
key : The key in to the section.

Return value:
Returns the float stored at the section and key, or 0.

Notes:
0 will be returned if the section or key does not exist.

See also:
INIFile.VectorY, INIFile.VectorZ, INIFile.NumberedVectorX, INIFile.NumberedVectorY, INIFile.NumberedVectorZ.


INIFile.VectorY

Access the y component of a vector in the INIFile object under section and key.

prototype float INIFile.VectorY( hinifile handle,
                                 string section,
                                 string key );

Parameters:
handle : The handle to the INIFile object
section : The section in the INIFile.
key : The key in to the section.

Return value:
Returns the float stored at the section and key, or 0.

Notes:
0 will be returned if the section or key does not exist.

See also:
INIFile.VectorX, INIFile.VectorZ, INIFile.NumberedVectorX, INIFile.NumberedVectorY, INIFile.NumberedVectorZ.


INIFile.VectorZ

Access the z component of a vector in the INIFile object under section and key.

prototype float INIFile.VectorZ( hinifile handle,
                                 string section,
                                 string key );

Parameters:
handle : The handle to the INIFile object
section : The section in the INIFile.
key : The key in to the section.

Return value:
Returns the float stored at the section and key, or 0.

Notes:
0 will be returned if the section or key does not exist.

See also:
INIFile.VectorX, INIFile.VectorY, INIFile.NumberedVectorX, INIFile.NumberedVectorY, INIFile.NumberedVectorZ.


Input

Package for functions relating to keyboard input, and the binding of Pog functions to keys.

Functions:

  • BindKey
  • CurrentInputScheme
  • KeyCombinations
  • NthInputSchemeName
  • NumInputSchemes
  • PurgeBindings
  • ResumeBindings
  • SelectInputScheme
  • SuspendBindings


Input.BindKey

Bind a key to a Pog function.

prototype void Input.BindKey( string function,
                              string key );

Parameters:
function : The Pog function to execute.
key : The key to bind to the function - an entry in the inputs.ini initialisation file.

Return value:
None.

Notes:
Example:
To bind the 'r' key to a Pog function MyPackage.MyFunction, put the following lines in the inputs.ini file:
[AnySection.CallMyFunction]
Keyboard, R
and make the following call to Input.BindKey:
Input.BindKey( "MyPackage.MyFunction", "AnySection.CallMyFunction" );

This function should only be called once - before the binding is used.


Input.NthInputSchemeName

Get the name of the Nth input scheme

prototype string Input.NthInputSchemeName( int index );

Parameters:
index: The input scheme number that you require the name for.

Return value:
The name of the input scheme as a string.

See Also:
 CurrentInputScheme, NumInputSchemes, SelectInputScheme


Input.KeyCombinations

Returns a neatly formatted string of key combinations for the given function.

prototype string Input.KeyCombinations( string function );

Parameters:
function : The Pog function to get the bindings for..

Return value:
The key bindings as a string.


Input.NumInputSchemes

Get the number of input schemes available in the resource tree.

prototype int Input.NumInputSchemes();

Parameters:
None

Return value:
The number of key input schemes as an int.

See Also:
 CurrentInputScheme, NthInputSchemeName, SelectInputScheme


Input.CurrentInputScheme

Get the index of the current input scheme.

prototype int Input.CurrentInputScheme();

Parameters:
None

Return value:
The index of the current input scheme as an int.

See Also:
 NthInputSchemeName, NumInputSchemes, SelectInputScheme


Input.PurgeBindings

Purge all scriptable key bindings.

prototype void Input.PurgeBindings();

Parameters:
None

Return value:
None.


Input.ResumeBindings

Resumes all key bindings after a suspend.

prototype void Input.ResumeBindings();

Parameters:
None

Return value:
None.

See Also:
 SuspendBindings


Input.SelectInputScheme

Switch to the given input scheme

prototype Input.SelectInputScheme( int index );

Parameters:
index: The index of the input scheme you want to activate.

Return value:
The index of the current input scheme as an int.

See Also:

CurrentInputScheme, NthInputSchemeName, NumInputSchemes


Input.SuspendBindings

Suspend all key bindings.

prototype void Input.SuspendBindings();

Parameters:
None

Return value:
None.

See Also:
 ResumeBindings


Lock

This package provides lock objects which can be used for multitasking synchronization. Lock objects can be created and destroyed when no longer needed. Tasks use lock objects by claiming them. Claiming a lock object stops other tasks from claiming the same lock, this can be interpreted by the task to mean that it can/cannot do something.

Type definitions:

  • hlock

Functions:

  • Create
  • Destroy
  • Find
  • Claim
  • Release


Lock.hlock

This is a handle to a lock object.

hlock : hobject;

Notes:
Lock handles are returned when a lock is created or can be found from the lock name.

See also:
Lock.Create, Lock.Find.


Lock.Claim

This function tries to claim a lock for this task. If the lock is already claimed it fails.

prototype bool Lock.Claim( hlock lock );

Parameters:
lock : The handle of the lock to claim.

Return value:
Returns a boolean indicating whether the lock was claimed. True indicates that this task has claimed the lock, false indicates that the lock has been claimed by another task.

Notes:
A task trying to claim a lock it has already claimed will get the return value true. The task should release the lock after doing the appropriate work.

See also:
Lock.Release.


Lock.Create

Create a lock object and return the new lock handle.

prototype hlock Lock.Create( string name );

Parameters:
name : Name to give to the new lock.

Return value:
Returns the hlock handle to the lock so that the lock can be used.

Notes:
The lock name must be unique or the returned handle will contain 'none'. The lock must be destroyed or it will cause a memory leak.

See also:
Lock.Destroy, Lock.Find.


Lock.Destroy

Destroys a lock object. Can only be destroyed if the lock is not claimed or is claimed by this task.

prototype Lock.Destroy( hlock lock );

Parameters:
lock : The handle of the lock to destroy.

Return value:
None.

Notes:
All locks that are created must be destroyed to stop memory leaks.

See also:
Lock.Create.


Lock.Find

This function searches for a lock object that has been created with the same name, and returns a handle to this object if it is present.

prototype hlock Lock.Find( string name );

Parameters:
name : Name of the lock to try and find the handle.

Return value:
Returns a handle to the lock object with this name if it is present.

Notes:
Returns 'none' if a matching lock could not be found.

See also:
Lock.Create.


Lock.Release

This function releases a lock from the control of this task.

prototype Lock.Release( hlock lock );

Parameters:
lock : The handle of the lock to release.

Return value:
None.

Notes:
A lock can only be released by the task that claimed the lock.

See also:
Lock.Claim.


Object Package

The object package provides access to Flux object properties. This allows properties to be changed, added, removed, accessed and checked for existence.

Functions:

  • AddBoolProperty
  • AddFloatProperty
  • AddHandleProperty
  • AddIntProperty
  • AddListProperty
  • AddStringProperty
  • AddVectorProperty
  • BoolProperty
  • FloatProperty
  • HandleProperty
  • IDModulus
  • IntProperty
  • ListProperty
  • PropertyExists
  • RemoveProperty
  • SetBoolProperty
  • SetFloatProperty
  • SetHandleProperty
  • SetIntProperty
  • SetListProperty
  • SetStringProperty
  • SetVectorProperty
  • StringProperty
  • VectorPropertyX
  • VectorPropertyY
  • VectorPropertyZ


Object.AddBoolProperty

Adds a bool property to an object and sets its initial value.

prototype bool Object.AddBoolProperty( hobject o,
                                        string property,
                                        bool v );

Parameters:
o : The object handle for the object being altered.
property : The name of the user property to be added to the object.
v : The initial value to assign to the property.

Return value:
Returns a boolean indicating if a user property was successfully created.

Notes:
A user property cannot be added if it already exists as either a built in or user property.

See also:
Object.AddHandleProperty, Object.AddIntProperty, Object.AddStringProperty, Object.AddStringProperty, Object.AddBoolProperty


Object.AddFloatProperty

Adds a float property to an object and sets its initial value.

prototype bool Object.AddFloatProperty( hobject o,
                                        string property,
                                        float v );

Parameters:
o : The object handle for the object being altered.
property : The name of the user property to be added to the object.
v : The initial value to assign to the property.

Return value:
Returns a boolean indicating if a user property was successfully created.

Notes:
A user property cannot be added if it already exists as either a built in or user property.

See also:
Object.AddHandleProperty, Object.AddIntProperty, Object.AddStringProperty, Object.AddStringProperty, Object.AddBoolProperty


Object.AddHandleProperty

Adds a handle property to an object and sets its initial value.

prototype bool Object.AddHandleProperty( hobject o,
                                         string property,
                                         hobject v );

Parameters:
o : The object handle for the object being altered.
property : The name of the user property to be added to the object.
v : The initial value to assign to the property.

Return value:
Returns a boolean indicating if a user property was successfully created.

Notes:
A user property cannot be added if it already exists as either a built in or user property.

See also:
Object.AddFloatProperty, Object.AddIntProperty, Object.AddStringProperty, Object.AddStringProperty, Object.AddBoolProperty


Object.AddIntProperty

Adds a int property to an object and sets its initial value.

prototype bool Object.AddIntProperty( hobject o,
                                      string property,
                                      int v );

Parameters:
o : The object handle for the object being altered.
property : The name of the user property to be added to the object.
v : The initial value to assign to the property.

Return value:
Returns a boolean indicating if a user property was successfully created.

Notes:
A user property cannot be added if it already exists as either a built in or user property.

See also:
Object.AddFloatProperty, Object.AddHandleProperty, Object.AddStringProperty, Object.AddStringProperty, Object.AddBoolProperty


Object.AddListProperty

Adds a list property to an object and sets its initial value.

prototype bool Object.AddListProperty( hobject o,
                                        string property,
                                        list v );

Parameters:
o : The object handle for the object being altered.
property : The name of the user property to be added to the object.
v : The initial value to assign to the property.

Return value:
Returns a boolean indicating if a user property was successfully created.

Notes:
A user property cannot be added if it already exists as either a built in or user property.

See also:
Object.AddHandleProperty, Object.AddFloatProperty, Object.AddIntProperty, Object.AddStringProperty, Object.AddBoolProperty


Object.AddStringProperty

Adds a string property to an object and sets its initial value.

prototype bool Object.AddStringProperty( hobject o,
                                         string property,
                                         string v );

Parameters:
o : The object handle for the object being altered.
property : The name of the user property to be added to the object.
v : The initial value to assign to the property.

Return value:
Returns a boolean indicating if a user property was successfully created.

Notes:
A user property cannot be added if it already exists as either a built in or user property.

See also:
Object.AddFloatProperty, Object.AddHandleProperty, Object.AddIntProperty, Object.AddBoolProperty, Object.AddListProperty


Object.AddVectorProperty

Adds a vector property to an object and sets its initial value.

prototype bool Object.AddVectorProperty( hobject o,
                                         string property,
                                         float x,
                                         float y,
                                         float z );

Parameters:
o : The object handle for the object being altered.
property : The name of the user property to be added to the object.
x : The x component of a value to assign to the property.
y : The y component of a value to assign to the property.
z : The z component of a value to assign to the property.

Return value:
Returns a boolean indicating if a user property was successfully created.

Notes:
A user property cannot be added if it already exists as either a built in or user property.

See also:
Object.SetVectorProperty, Object.VectorPropertyX, Object.VectorPropertyY, Object.VectorPropertyZ.


Object.BoolProperty

Retrieves a value from an object property.

prototype bool Object.BoolProperty( hobject o,
                                  string property );

Parameters:
o : The object handle which is being accessed.
property : The name of the property in the object that is required.

Return value:
Returns the value for the given property of this object.

Notes:
Should this function fail it returns a default value.

See also:
Object.FloatProperty, Object.HandleProperty, Object.StringProperty, Object.ListProperty


Object.FloatProperty

Retrieves a value from an object property

prototype float Object.FloatProperty( hobject o,
                                      string property );

Parameters:
o : The object handle which is being accessed.
property : The name of the property in the object that is required.

Return value:
Returns the value for the given property of this object.

Notes:
Should this function fail it returns a default value.

See also:
Object.HandleProperty, Object.IntProperty, Object.StringProperty, Object.BoolProperty, Object.ListProperty


Object.HandleProperty

Retrieves a value from an object property

prototype handle Object.HandleProperty( hobject o,
                                        string property );

Parameters:
o : The object handle which is being accessed.
property : The name of the property in the object that is required.

Return value:
Returns the value for the given property of this object.

Notes:
Should this function fail it returns a default value.

See also:
Object.FloatProperty, Object.IntProperty, Object.StringProperty, Object.BoolProperty, Object.ListProperty


Object.IDModulus

Return the modulus of the object's id with the int supplied.

prototype int Object.IDModulus( hobject o,
                                  int modulus );

Parameters:
o : The object handle which is being accessed.
modulus : The int for the modulus.

Return value:
Returns the value for the given property of this object.

Notes:
Should this function fail it returns a default value.

See also:
Object.FloatProperty, Object.HandleProperty, Object.StringProperty, Object.BoolProperty, Object.ListProperty


Object.IntProperty

Retrieves a value from an object property

prototype int Object.IntProperty( hobject o,
                                  string property );

Parameters:
o : The object handle which is being accessed.
property : The name of the property in the object that is required.

Return value:
Returns the value for the given property of this object.

Notes:
Should this function fail it returns a default value.

See also:
Object.FloatProperty, Object.HandleProperty, Object.StringProperty, Object.BoolProperty, Object.ListProperty


Object.ListProperty

Retrieves a value from an object property

prototype list Object.ListProperty( hobject o,
                                  string property );

Parameters:
o : The object handle which is being accessed.
property : The name of the property in the object that is required.

Return value:
Returns the value for the given property of this object.

Notes:
Should this function fail it returns a default value.

See also:
Object.FloatProperty, Object.HandleProperty, Object.StringProperty, Object.BoolProperty


Object.PropertyExists

Checks to see if the user property property exits in object o.

prototype bool Object.PropertyExists( hobject o,
                                      string property );

Parameters:
int_param : What the int param does.
float_param : What the float param does.

Return value:
Returns a boolean indicating the presence or absence of the property in the object.


Object.RemoveProperty

Removes a user property from an object regardless of the property type.

prototype Object.RemoveProperty( hobject o,
                                 string property );

Parameters:
o : The object handle for the object being altered.
property : The name of the user property to be removed from the object.

Return value:
What the return value or values are.

Notes:
An in built property cannot be removed using this method.


Object.SetBoolProperty

Sets a bool object property value.

prototype Object.SetBoolProperty( hobject o,
                                    string property,
                                    bool v );

Parameters:
o : The object handle for the object being altered.
property : The name of the property in the object that is to be set.
v : The value to assign to the property.

Notes:
Sets a given object property to the value v.

See also:
Object.SetFloatProperty, Object.SetIntProperty, Object.SetStringProperty, Object.SetListProperty, Object.SetListProperty, Object.SetBoolProperty


Object.SetFloatProperty

Sets a float object property value.

prototype Object.SetFloatProperty( hobject o,
                                   string property,
                                   float v );

Parameters:
o : The object handle for the object being altered.
property : The name of the property in the object that is to be set.
v : The value to assign to the property.

Notes:
Sets a given object float property to the value v.

See also:
Object.SetHandleProperty, Object.SetIntProperty, Object.SetStringProperty, Object.SetListProperty, Object.SetBoolProperty


Object.SetHandleProperty

Sets a handle object property value.

prototype Object.SetHandleProperty( hobject o,
                                    string property,
                                    hobject v );

Parameters:
o : The object handle for the object being altered.
property : The name of the property in the object that is to be set.
v : The value to assign to the property.

Notes:
Sets a given object property to the value v.

See also:
Object.SetFloatProperty, Object.SetIntProperty, Object.SetStringProperty, Object.SetListProperty, Object.SetBoolProperty


Object.SetIntProperty

Sets an int object property value.

prototype Object.SetIntProperty( hobject o,
                                 string property,
                                 int v );

Parameters:
o : The object handle for the object being altered.
property : The name of the property in the object that is to be set.
v : The value to assign to the property.

Notes:
Sets a given object int property to the value v.

See also:
Object.SetFloatProperty, Object.SetHandleProperty, Object.SetStringProperty, Object.SetListProperty, Object.SetBoolProperty


Object.SetListProperty

Sets a bool object property value.

prototype Object.SetListProperty( hobject o,
                                    string property,
                                    list v );

Parameters:
o : The object handle for the object being altered.
property : The name of the property in the object that is to be set.
v : The value to assign to the property.

Notes:
Sets a given object property to the value v.

See also:
Object.SetFloatProperty, Object.SetIntProperty, Object.SetStringProperty, Object.SetBoolProperty


Object.SetStringProperty

Sets an object string property value.

prototype Object.SetStringProperty( hobject o,
                                    string property,
                                    string v );

Parameters:
o : The object handle for the object being altered.
property : The name of the property in the object that is to be set.
v : The value to assign to the property.

Notes:
Sets a given object property to the value v.

See also:
Object.SetFloatProperty, Object.SetHandleProperty, Object.SetIntProperty, Object.SetListProperty, Object.SetBoolProperty


Object.SetVectorProperty

Sets a vector object property value.

prototype Object.SetVectorProperty( hobject o,
                                    string property,
                                    float x,
                                    float y,
                                    float z );

Parameters:
o : The object handle for the object being altered.
property : The name of the property in the object that is to be set.
x : The x component of a vector to assign to the property.
y : The y component of a vector to assign to the property.
z : The z component of a vector to assign to the property.

Notes:
Sets a given object vector property to the value defined from the given components.

See also:
Object.VectorPropertyX, Object.VectorPropertyY, Object.VectorPropertyZ, Object.AddVectorProperty.


Object.StringProperty

Retrieves a value from an object property

prototype string Object.StringProperty( hobject o,
                                        string property );

Parameters:
o : The object handle which is being accessed.
property : The name of the property in the object that is required.

Return value:
Returns the value for the given property of this object.

Notes:
Should this function fail it returns a default value.

See also:
Object.FloatProperty, Object.HandleProperty, Object.IntProperty, Object.BoolProperty, Object.ListProperty


Object.VectorPropertyX

Retrieves the x component of a vector from an object property

prototype float Object.VectorPropertyX( hobject o,
                                        string property );

Parameters:
o : The object handle which is being accessed.
property : The name of the property in the object that is required.

Return value:
Returns the x component of a vector for the given property of this object.

Notes:
Should this function fail it returns a default value of 0.

See also:
Object.VectorPropertyY, Object.VectorPropertyZ.


Object.VectorPropertyY

Retrieves the y component of a vector from an object property

prototype float Object.VectorPropertyY( hobject o,
                                        string property );

Parameters:
o : The object handle which is being accessed.
property : The name of the property in the object that is required.

Return value:
Returns the y component of a vector for the given property of this object.

Notes:
Should this function fail it returns a default value of 0.

See also:
Object.VectorPropertyX, Object.VectorPropertyZ.


Object.VectorPropertyZ

Retrieves the z component of a vector from an object property

prototype float Object.VectorPropertyZ( hobject o,
                                        string property );

Parameters:
o : The object handle which is being accessed.
property : The name of the property in the object that is required.

Return value:
Returns the z component of a vector for the given property of this object.

Notes:
Should this function fail it returns a default value of 0.

See also:
Object.VectorPropertyX, Object.VectorPropertyY.


State

A state is a means of saving a task between game sessions so that it can be restarted later. The State package deals with the creation, manipulation and destruction of states.

See the States section for more information.

Type definitions:

  • hstate

Functions:

  • Cast

  • Create

  • Destroy

  • DestroyAll

  • Find

  • IsLocked

  • Lock

  • Progress

  • Restore

  • SetProgress

  • Task

  • Unlock


State.hstate

Handle to a state object - representing the state of a particular Pog task.

hstate : hobject;

Notes:
This handle type is used to refer to the status of a game Pog task..


Task.Cast

Casts a handle to an object to a handle to a task.

prototype Task.Cast( hobject handle );

Parameters:
handle : The object handle to cast to a task handle.

Return value:
Returns a handle to a task.


State.Create

Create a state and associate it with the given task. Assign the given progress value to the state.

prototype hstate State.Create( htask task, int progress );

Parameters:
task : The task to create the state for.
progress : The progress value, as an int.

Return value:
A handle to the created state.

See also:
State.Destroy


State.Find

Find the state associated with a given task.

prototype hstate State.Find( htask task );

Parameters:
task : The task to find the state for.

Return value:
A handle to a state, or none if no state found.

See also:
State.Task


State.Destroy

Destroy the state associated with a given task.

prototype State.Destroy( htask task );

Parameters:
task : The task to destroy the state for.

Return value:
None

See also:
State.Create, State.DestroyAll


State.DestroyAll

Destroy all states.

prototype State.DestroyAll();

Parameters:
None

Return value:
None

See also:
State.Destroy


State.IsLocked

Check a state to see if it's locked.

prototype bool State.IsLocked( hstate state );

Parameters:
state : The state to check.

Return value:
True if locked, false otherwise.

See also:
State.Lock, State.Unlock


State.Lock

Lock the state, so that no further SetProgress calls can be made.

prototype State.Lock( hstate state );

Parameters:
state : The state to lock

Return value:
None.

See also:
 State.IsLocked, State.Unlock


State.SetProgress

Set the given state's progress value.

prototype State.SetProgress( hstate state, int progress );

Parameters:
state : The task to set the progress value for.
progress : The progress value, as an int.

Return value:
None.

See also:
State.Progress


State.Progress

Get the given state's progress value.

prototype int State.Progress( hstate state );

Parameters:
state : The state to set the progress value for.

Return value:
The state's progress value, as an int.

See also:
State.SetProgress


State.Restore

Restart the associated task for the given state, if currently halted.

prototype State.Restore( hstate state );

Parameters:
state : The state restart the task for.

Return value:
None.


State.Task

Return the task associated with a given state, if it exists.

prototype htask State.Task( hstate state );

Parameters:
state : The state to find the task for.

Return value:
A task for the specified state.

See also:
 State.Find


State.Unlock

Unlock the state.

prototype State.Unlock( hstate state );

Parameters:
state : The state to unlock

Return value:
None.

See also:
State.Lock, State.IsLocked


Stream

The Stream package is used to play streaming sound, such as music and sound effects. Streams are assumed to be in a codec that's currently installed, and in a format that DirectSound can handle.

Functions:

  • Play
  • Stop
  • IsPlaying
  • IsPlayingURL


Stream.Play

Play an audio stream in a given slot.

prototype Stream.Play( int slot, string url, bool fade, bool loop );

Parameters:
slot : The slot number to use when playing the stream.
url : The file name of the stream. In flux URL format, e.g. "sound:/audio/music/a1_theme"
fade : Specify if the stream fades out when it ends.
loop : Specify if the stream loops continously.

Return value:
None.

Notes:
Streams are assumed to be in a codec that's installed, and that DirectSound can handle.

See also:
Stream.Stop


Stream.Stop

Stop a stream that's playing in a given slot.

prototype Stream.Stop( int slot, bool fade );

Parameters:
slot : The slot number of the stream to stop.
fade : Specify if the stream fades out when it's stopped.

Return value:
None.

See also:
Stream.Play


Stream.IsPlaying

Check if a stream is playing in a given slot.

prototype bool Stream.IsPlaying( int slot );

Parameters:
slot : The slot number to check.

Return value:
TRUE if a stream is playing in the given slot, false if not.

See also:
Stream.IsPlayingURL


Stream.IsPlayingURL

Check if a given stream URL is playing.

prototype bool Stream.Play( int slot, string url );

Parameters:
slot : The slot number to check.
url : The file name of the stream. to check.

Return value:
TRUE if the given url is playing in the given slot.

See also:
IsPlaying


Sim

A sim is a simulated object in the flux engine, such as a space ship or projectile.

This package facilitates the creation, manipulation and querying of sim objects.

Type definitions:

  • hsim

Functions:

Misc

  • Cast
  • Create
  • Destroy
  • FindByName
  • FindByWildcard
  • First
  • Group
  • IsInFOV
  • Name
  • Preload
  • TemplateName

Placement, Orientation and Speed

These functions deal with the placing, orientation, and speed of sims.

  • CopyOrientation
  • DistanceBetween
  • DistanceBetweenCentres
  • PlaceAt
  • PlaceBetween
  • PlaceInFrontOf
  • PlaceNear
  • PlaceRelativeTo
  • PlaceRelativeToInside
  • PointAt
  • PointAway
  • SetAngularVelocity
  • SetAngularVelocityEuler
  • SetOrientationEuler
  • SetVelocity
  • SetVelocityLocalToSim
  • Speed

Sim Properties

These functions deal with setting some of the built in properties of sims.

The 'interesting' property is used to define if a sim is simulated when the player is not nearby. Sims are not 'interesting' by default.

The 'cullable' property is used to define if a sim is culled ( silently destroyed ) when the player is out of range (400km). Sims are cullable by default.

  • IsAlive
  • IsCullable
  • IsCollisionOn
  • IsDead
  • IsHidden
  • IsInteresting
  • SetCollision
  • SetCullable
  • SetHidden
  • SetInteresting
  • SetMass
  • SetRadius

Child Sims

Child sims are sims that are attached to other sims. These functions deal with the manipulation of child sims.

  • AddChildRelativeTo
  • AttachChild
  • Children
  • ChildCount
  • DetachChild
  • FirstChild
  • NextSibling
  • NthChild
  • Parent

Subsims

Subsims are a special type of sim that gives the sim its functionality. Subsims allow a sim to move, shoot and perform other functions.

These functions deal with the manipulation of subsims of a sim. See the Subsim package for more subsim functions.

  • AddSubsim
  • FindSubsimByName
  • NthSubsim
  • RemoveNthSubsim
  • SubsimCount

Channels

Channels are controls for features defined in Avatar lightwave scenes, that allow the manipulation of avatar special effects.

  • AvatarAddChannel
  • AvatarChannelValue
  • AvatarRemoveChannel
  • AvatarSetChannel


Sim.hsim

Handle to a sim object - representing the simulation of a game object.

hsim : hobject;

Properties:
Name | Type | Read | Write | Description
position | vector | • |  | The position of the object
velocity | vector | • |  | The velocity vector of the object
angular velocity | vector | • |  | The angular velocity vector of the object
mass | float | • | • | The mass of the object
radius | float | • | • | The radius of the object
remote_id | handle | • |  | A handle to the object
template_name | string | • |  | The name of the template ini file for this sim

Notes:
This handle type is used to refer to the simulations of game objects.


Sim.Cast

Casts a handle to an object to a handle to a sim.

prototype hsim Sim.Cast( hobject handle );

Parameters:
handle : The object handle to cast to a sim handle.

Return value:
Returns a handle to a sim.


Sim.Create

Create a sim.

prototype hsim Sim.Create( string template, string name );

Parameters:
template : The name of the sim template to create.
name : The name to assign to the newly created sim.

Return value:
Returns a handle to the newly created sim.

Notes:
The name of the sim template is a resource url and should point to a suitable INI file.


Sim.Destroy

Silently destroy a sim, removing it from the world.

prototype Sim.Destroy( hsim sim );

Parameters:
sim : The sim to destroy

Return value:
None.

See also:
iSim.Kill, Sim.Create


Sim.FindByName

Find a sim in the world from its name.

prototype hsim Sim.FindByName( string name );

Parameters:
name : The name to search on.

Return value:
A handle to the sim discovered from the search.

Notes:
If the search is unsuccessful then a null handle is returned. If more than one sims have the same name then the first one found is returned.

See also:
Sim.FindByWildcard.


Sim.FindByWildcard

Find a set of sims in the world whose names match a given string, which may include wildcards.

prototype set Sim.FindByWildcard( string wildcard );

Parameters:
wildcard : A wildcard-laden string to search on.

Return value:
Returns a set of handles to sims whose names match the given string.

Notes:
The string may contain ? or * wildcard characters. The former will match exactly one of any character and the latter will match zero or more of any character.

See also:
Sim.FindByName.


Sim.First

Finds the first sim in the world.

prototype hsim Sim.First();

Parameters:
None.

Return value:
Returns the first sim in the world.

Notes:
If there are no sims in the world then a null handle will be returned.


Sim.Group

Returns the sim's group if it has been added to a group.

prototype hgroup Sim.Group( hsim sim );

Parameters:
sim : The sim to query.

Return value:
Returns a handle to the sims group.


Sim.IsInFOV

Returns true if sim2 is within the sim1 field of view.

prototype bool Sim.IsDead( hsim sim1 hsim sim2 float fov );

Parameters:
sim1 : The sim to check.
sim2 : The second sim to check.
fov : The field of view ( degrees ).

Return value:
Returns true if sim1 is in sim2's specified FOV.


Sim.Name

Returns the name of the sim.

prototype string Sim.Name( hsim sim );

Parameters:
sim : The sim to get the name from.

Return value:
Returns a string containing the name of the sim.


Sim.Preload

Preloads a sim from the given sim template INI file.

prototype Sim.Preload( string template );

Parameters:
template : The sim template to preload.

Return value:
None.

Notes:
This function preloads a sim template into a cache. This means that creating the first instance of a sim using this template will be quicker, since it will not require loading the template ini file.

See also:
Sim.Create.


Sim.TemplateName

Returns the resource template originally used to create the sim.

prototype string Sim.TemplateName( hsim sim );

Parameters:
sim : The sim to get the template for.

Return value:
Returns a string containing the name of the sim's template.


Sim.CopyOrientation

Give one sim the orientation of the other.

prototype void Sim.CopyOrientation( hsim target,
                                    hsim source );

Parameters:
target : The sim to give the orientation to.
source : The sim to copy the orientation from.

Return value:
None.


Sim.DistanceBetween

Calculate the distance between two sims.

prototype float Sim.DistanceBetween( hsim sim1,
                                     hsim sim2 );

Parameters:
sim1 : One of the sims.
sim2 : The other sim.

Return value:
The distance between the two sims as a floating point number.

Notes:
This functions takes the radii of the sims into account.

If the two sims are touching or intersecting then this function returns zero.

See also:
Sim.DistanceBetweenCentres.


Sim.DistanceBetweenCentres

Calculate the distance between the centres of sims.

prototype float Sim.DistanceBetweenCentres( hsim sim1,
                                            hsim sim2 );

Parameters:
sim1 : One of the sims.
sim2 : The other sim.

Return value:
The distance between the centers of the two sims as a floating point number.

See also:
Sim.DistanceBetween.


Sim.PlaceAt

Place a sim at the position of another sim.

prototype void Sim.PlaceAt( hsim sim,
                            hsim marker );

Parameters:
sim : The sim to place.
marker : The sim to place at.

Return value:
None.

Notes:
This function can be used to move a sim within a system or to place a newly created sim for the first time.

This function will prevent two sims being placed in a colliding state. If an attempt is made to place two colliders such that they overlap then the sim being placed will be moved to a nearby non-colliding position.

See also:
Sim.PlaceRelativeTo, Sim.PlaceRelativeToInside, Sim.PlaceBetween, Sim.PlaceNear, Sim.PlaceInFrontOf


Sim.PlaceBetween

Place a sim at a position between two other sims.

prototype void Sim.PlaceBetween( hsim sim,
                                 hsim begin,
                                 hsim end,
                                 float distance );

Parameters:
sim : The sim to place.
begin : The sim will be placed between this sim and the end sim.
end : The sim will be placed between the begin and this sim.
distance : A value between 0 and 1 representing how far towards end from begin to place the sim.

Return value:
None.

Notes:
This function can be used to move a sim within a system or to place a newly created sim for the first time.

This function will prevent two sims being placed in a colliding state. If an attempt is made to place two colliders such that they overlap then the sim being placed will be moved to a nearby non-colliding position.

See also:
Sim.PlaceAt, Sim.PlaceRelativeTo, Sim.PlaceRelativeToInside, Sim.PlaceNear, Sim.PlaceInFrontOf


Sim.PlaceInFrontOf

Place a sim in front of another sim.

prototype void Sim.PlaceInFrontOf( hsim sim,
                                    hsim marker,
                                    float distance );

Parameters:
sim : The sim to place.
marker : The sim to place relative to.
distance : The distance in front of the sim.

Return value:
None.

Notes:

This function will prevent two sims being placed in a colliding state. If an attempt is made to place two colliders such that they overlap then the sim being placed will be moved to a nearby non-colliding position.

See also:
Sim.PlaceAt, Sim.PlaceRelative, Sim.PlaceRelativeToInside, Sim.PlaceBetween, Sim.PlaceNear, Sim.PlaceInFrontOf


Sim.PlaceNear

Place a sim at a postion at a given radius from another sim.

prototype void Sim.PlaceNear( hsim sim,
                              hsim marker,
                              float distance );

Parameters:
sim : The sim to place.
marker : The sim to place near.
distance : The radius from marker to place sim.

Return value:
None.

Notes:
This function will place the body at a random position on the surface of the sphere with radius distance metres around the marker sim.

This function will prevent two sims being placed in a colliding state. If an attempt is made to place two colliders such that they overlap then the sim being placed will be moved to a nearby non-colliding position.

See also:
Sim.PlaceAt, Sim.PlaceRelativeTo, Sim.PlaceRelativeToInside, Sim.PlaceBetween, Sim.PlaceInFrontOf


Sim.PlaceRelativeToInside

Place a sim at position relative to another sim, ignoring the sims radiuses.

prototype void Sim.PlaceRelativeToInside( hsim sim,
                                    hsim marker,
                                    float x,
                                    float y,
                                    float z );

Parameters:
sim : The sim to place.
marker : The sim to place relative to.
x : The x offset from marker.
y : The y offset from marker.
z : The z offset from marker.

Return value:
None.

Notes:
The offset is taken relative to the marker sim, i.e. in that sim's coordinates system.

Similiar to PlaceRelativeTo except it allows placement of objects inside other objects. Use with caution!

This function is very useful when you want to place two objects very close together without the auto-placement checking moving the objects out of collision.

See also:
Sim.PlaceAt, Sim.PlaceBetween, Sim.PlaceNear, Sim.PlaceInFrontOf


Sim.PlaceRelativeTo

Place a sim at position relative to another sim.

prototype void Sim.PlaceRelativeTo( hsim sim,
                                    hsim marker,
                                    float x,
                                    float y,
                                    float z );

Parameters:
sim : The sim to place.
marker : The sim to place relative to.
x : The x offset from marker.
y : The y offset from marker.
z : The z offset from marker.

Return value:
None.

Notes:
The offset is taken relative to the marker sim, i.e. in that sim's coordinates system.

This function will prevent two sims being placed in a colliding state. If an attempt is made to place two colliders such that they overlap then the sim being placed will be moved to a nearby non-colliding position.

See also:
Sim.PlaceAt, Sim.PlaceBetween, Sim.PlaceNear.


Sim.PointAt

Points one sim at another.

prototype void Sim.PointAt( hsim sim,
                            hsim marker );

Parameters:
sim : The sim to point.
marker : The sim to point at.

Return value:
None.

See also:
Sim.PointAway


Sim.PointAway

Points one sim away from another.

prototype void Sim.PointAway( hsim sim,
                            hsim marker );

Parameters:
sim : The sim to point.
marker : The sim to point away from.

Return value:
None.

See also:
Sim.PointAt


Sim.SetAngularVelocity

Gives a sim an angular velocity.

prototype void Sim.SetAngularVelocity( hsim sim,
                                       float x,
                                       float y,
                                       float z,
                                       float dps );

Parameters:
sim : The sim to alter.
x : The x coordinate of the angular velocity vector.
y : The y coordinate of the angular velocity vector.
z : The z coordinate of the angular velocity vector.
dps : The degrees per second of rotation to apply.

Return value:
None.

Notes:
The angular velocity vector is provides the direction in which the angular velocity will be provided. This vector is normalised, i.e. (200, -100, 0) will have the same effect as (2, -1, 0), and then the magnitude is set from the dps parameter.

See also:
Sim.SetAngularVelocityEuler.


Sim.SetAngularVelocityEuler

Gives a sim an angular velocity.

prototype void Sim.SetAngularVelocityEuler( hsim sim,
                                            hsim yaw,
                                            hsim pitch,
                                            hsim roll );

Parameters:
sim : The sim to alter.
yaw : The yaw to apply.
pitch : The pitch to apply.
roll : The roll to apply.

Return value:
None.

Notes:
Applies an angular velocity to the sim. The angular velocity is given in Euler angles - yaw, pitch and roll.

See also:
Sim.SetAngularVelocity.


Sim.SetOrientationEuler

Sets the orientation of a sim.

void Sim.SetOrientationEuler( hsim sim, float yaw, float pitch, float roll );
prototype void Sim.SetOrientationEuler( hsim sim,
                                        float yaw,
                                        float pitch,
                                        float roll, );

Parameters:
sim : The sim to alter.
yaw : The yaw to apply.
pitch : The pitch to apply.
roll : The roll to apply.

Return value:
None.

See also:
Sim.PointAt.


Sim.SetVelocity

Sets the world velocity of a sim.

prototype void Sim.SetVelocity( hsim sim,
                                float x,
                                float y,
                                float z );

Parameters:
sim : The sim to set.
x : The x component of the velocity vector.
y : The y component of the velocity vector.
z : The z component of the velocity vector.

Return value:
None.

See also:
Sim.SetVelocityLocalToSim.


Sim.SetVelocityLocalToSim

Sets the velocity of a sim local to its current direction.

prototype void Sim.SetVelocityLocalToSim( hsim sim,
                                float x,
                                float y,
                                float z );

Parameters:
sim : The sim whose velocity is to be set.
x : The local x component of the velocity vector.
y : The local y component of the velocity vector.
z : The local z component of the velocity vector.

Return value:
None.

Notes:
The local velocity components are defined relative to the current orientation of the sim. At the time of composition +ve x is to the right, -ve x is to the left, +ve y is up, -ve y is down, +ve z is forward and -ve z is backward

See also:
Sim.SetVelocity.


Sim.Speed

Returns the speed of the specified sim.

prototype float Sim.Speed( hsim sim );

Parameters:
sim : The sim to check.

Return value:
Returns the speed of the sim in metres per second as a float.


Sim.IsAlive

Returns true if the sim is alive.

prototype bool Sim.IsAlive( hsim sim );

Parameters:
sim : The sim to check.

Return value:
Returns true if the sim is alive

See also:
Sim.IsDead


Sim.IsCullable

Returns true if the given sim is cullable.

prototype bool Sim.IsCullable( hsim sim );

Parameters:
sim : The sim to check.

Return value:
Returns true if the cullable flag has been set for this sim.

See also:
Sim.SetCullable


Sim.IsCollisionOn

Returns true if collision detection is turned of for the given sim.

prototype bool Sim.IsCollisionOn( hsim sim );

Parameters:
sim : The sim to check.

Return value:
Returns true if collision detection is turned of for the given sim.

See also:
Sim.SetCollision


Sim.IsDead

Returns true if the sim is dead, or has been culled.

prototype bool Sim.IsDead( hsim sim );

Parameters:
sim : The sim to check.

Return value:
Returns true if the sim is dead

See also:
Sim.IsAlive


Sim.IsHidden

Returns true if the sim is hidden.

prototype bool Sim.IsHidden( hsim sim );

Parameters:
sim : The sim to check.

Return value:
Returns true if the sim has been hidden.

See also:
Sim.SetHidden


Sim.IsInteresting

Returns true if the interesting flag of the given sim has been set.

prototype bool Sim.IsInteresting( hsim sim );

Parameters:
sim : The sim to check.

Return value:
Returns true if the interesting flag has been set for this sim.

See also:
Sim.SetInteresting.


Sim.SetCollision

Turn collision on or off for a sim.

prototype Sim.SetCollision( hsim sim, bool on);

Parameters:
sim : The sim to change.
flag : true or false setting for the sim.

Notes:
This is Intended for cutscene use only.

See also:
Sim.IsCollisionOn


Sim.SetCullable

Sets or clears the cullable flag of a sim.

prototype Sim.SetCullable( hsim sim, bool flag );

Parameters:
sim : The sim to change.
flag : true or false setting for the sim.

See also:
Sim.IsCullable


Sim.SetHidden

Hides or unhides a sim.

prototype Sim.SetHidden( hsim sim, bool flag );

Parameters:
sim : The sim to change.
flag : true to hide, false to unhide.

See also:
Sim.IsHidden


Sim.SetInteresting

Sets or clears the interesting flag of a sim.

prototype Sim.SetInteresting( hsim sim, bool flag );

Parameters:
sim : The sim to change.
flag : true or false setting for the sim.

See also:
Sim.IsInteresting.


Sim.SetMass

Sets the mass of the specified sim.

prototype Sim.SetMass( hsim sim, float mass );

Parameters:
sim : The sim to change.
mass : The mass you wish to set.

Notes:
A value of zero sets infinite mass, making the object immovable.


Sim.SetRadius

Sets the radius of the specified sim.

prototype Sim.Radius( hsim sim, float radius );

Parameters:
sim : The sim to change.
radius : The radius you wish to set.


Sim.AddChildRelativeTo

Add the given child to the given parent at the given offset.

prototype void Sim.AddChildRelativeTo( hsim parent, hsim child, float x, float y, float z );

Parameters:
parent : The parent sim.
child : The child sim to attach.
x : X coordinate.
y : Y coordinate.
z : Z coordinate.

Return value:
None.

See also:
Sim.AttachChild, Sim.Children, Sim.ChildCount, Sim.DetachChild, Sim.FirstChild, Sim.NextSibling, Sim.NthChild, Sim.Parent


Sim.AttachChild

Attach the sim child as a child of the sim parent, keeping their current physical locations.

prototype void Sim.AttachChild( hsim parent, hsim child );

Parameters:
parent : The parent sim.
child : The child sim to attach.

Return value:
None.

See also:
Sim.AddChildRelativeTo, Sim.Children, Sim.ChildCount, Sim.DetachChild, Sim.FirstChild, Sim.NextSibling, Sim.NthChild, Sim.Parent


Sim.Children

Get a set of all the children around a given sim.

prototype set Sim.Children( hsim sim );

Parameters:
sim : The sim to query.

Return value:
A set of handles to sim - the children of the given sim.

Notes:
If an invalid sim is given then an empty set is returned.


Sim.ChildCount

Returns the the count of a sims children.

prototype int Sim.ChildCount( hsim sim );

Parameters:
sim : The sim to query.

Return value:
Returns the number of children of the given sim.

See also:
Sim.AddChildRelativeTo, Sim.AttachChild, Sim.Children, Sim.DetachChild, Sim.FirstChild, Sim.NextSibling, Sim.NthChild, Sim.Parent


Sim.DetachChild

Detach the sim child from its sim parent, keeping their current physical locations.

prototype void Sim.DetachChild( hsim parent, hsim child );

Parameters:
parent : The parent sim.
child : The child sim to detach.

Return value:
None.

See also:
Sim.AddChildRelativeTo, Sim.AttachChild, Sim.Children, Sim.ChildCount, Sim.FirstChild, Sim.NextSibling, Sim.NthChild, Sim.Parent


Sim.FirstChild

Find the first child of a sim.

prototype hsim Sim.FirstChild( hsim sim );

Parameters:
sim : The sim to query.

Return value:
Returns the first child of the given sim.

Notes:
Sims form a tree. This means that a sim can have a parent and/or a group of children. A sim only stores its first child but that first child stores one of its siblings. Thus a child-sibling tree is formed. A given sim can traverse its children by first looking at its first child, then looking at that child's next sibling, then looking at that sim's next sibling and so on.

If the given sim has no children then a null handle is returned.

See also:
Sim.NextSibling, Sim.Parent.


Sim.NextSibling

Returns the next sibling of a given sim.

prototype hsim Sim.NextSibling( hsim sim );

Parameters:
sim : The sim to query.

Return value:
Returns the next sibling of a given sim.

Notes:
Sims form a tree. This means that a sim can have a parent and/or a group of children. A sim only stores its first child but that first child stores one of its siblings. Thus a child-sibling tree is formed. A given sim can traverse its children by first looking at its first child, then looking at that child's next sibling, then looking at that sim's next sibling and so on. If the given sim has no next sibling (i.e. if it is the last child of it's parent) then the function returns a null handle.

See also:
Sim.AddChildRelativeTo, Sim.AttachChild, Sim.Children, Sim.ChildCount, Sim.DetachChild, Sim.FirstChild, Sim.NthChild, Sim.Parent


Sim.NthChild

Returns the nth child of a given sim.

prototype hsim Sim.NthChild( hsim sim, int number );

Parameters:
sim : The sim to query.
number : The number of the child you wish to find.

Return value:
Returns the nth. child of a given sim.

Notes:
If the given child number doesn't exist then the function returns a null handle.

See also:
Sim.AddChildRelativeTo, Sim.AttachChild, Sim.Children, Sim.ChildCount, Sim.DetachChild, Sim.FirstChild, Sim.NextSibling, Sim.Parent


Sim.Parent

Returns the parent of the given sim.

prototype hsim Sim.Parent( hsim sim );

Parameters:
sim : The sim to query.

Return value:
Returns the parent of the given sim.

Notes:
If the given sim has no parent then the function returns a null handle.

See also:
Sim.FirstChild, Sim.NextSibling.


Sim.AddSubsim

Adds the subsim into the sim.

prototype void Sim.AddSubsim( hsim sim, hsubsim subsim );

Parameters:
sim : The sim.
subsim : The subsim to attach.

Return value:
None.

Notes:
The subsim will be placed at the centre of the sim. See the Subsim documentation for details of how to place and orient a subsim on its sim.

See also:
Subsim, Sim.SubsimCount, Sim.FindSubsimByName, Sim.NthSubsim, Sim.RemoveNthSubsim


Sim.FindSubsimByName

Finds the subsim with the given name on a sim.

prototype hsubsim Sim.FindSubsimByName( hsim sim, string name );

Parameters:
sim : The sim to query.
name : The name of the subsim you wish to find.

Return value:
Returns the named subsim.

Notes:
If the given subsim name doesn't exist then the function returns a null handle.

See also:
Subsim, Sim.AddSubsim, Sim.SubsimCount, Sim.NthSubsim, Sim.RemoveNthSubsim


Sim.NthSubsim

Returns the nth subsim of a given sim.

prototype hsubsim Sim.NthSubsim( hsim sim, int number );

Parameters:
sim : The sim to query.
number : The number of the subsim you wish to find.

Return value:
Returns the nth. subsim of a given sim.

Notes:
If the given subsim number doesn't exist then the function returns a null handle.

See also:
Subsim, Sim.AddSubsim, Sim.SubsimCount, Sim.RemoveNthSubsim, Sim.FindSubsimByName


Sim.RemoveNthSubsim

Removes the nth subsim of a given sim. All other subsims are shuffled downwards.

prototype hsim Sim.RemoveNthSubsim( hsim sim, int number );

Parameters:
sim : The sim to query.
number : The number of the subsim you wish to remove.

Return value:
Returns the handle to the removed subsim.

Notes:
If the given subsim number doesn't exist then the function returns a null handle.

See also:
Subsim, Sim.AddSubsim, Sim.SubsimCount, Sim.FindSubsimByName, Sim.NthSubsim


Sim.SubsimCount

Returns the the count of a sims subsims..

prototype int Sim.SubsimCount( hsim sim );

Parameters:
sim : The sim to query.

Return value:
Returns the number of subsims of the given sim.

See also:
Subsim, Sim.AddSubsim, Sim.FindSubsimByName, Sim.NthSubsim, Sim.RemoveNthSubsim


Sim.AvatarAddChannel

Creates a channel called name onto the sim's avatar.

prototype Sim.AvatarAddChannel( hsim sim, string name, float init_value);

Parameters:
sim : The sim.
name : The name of the channel.
init_value : The default value for the channel.

Return value:
None.

Notes:
The name of the channel must match the name as defined in the Avatar's lightwave scene file.

See also:
Sim.A vatarChannelValue, Sim.AvatarRemoveChannel, Sim.A vatarSetChannel


Sim.AvatarChannelValue

Find the current value of the channel called name from the sim's avatar.

prototype float Sim.AvatarChannelValue( hsim sim, string name);

Parameters:
sim : The sim.
name : The name of the channel.

Return value:
A float containing the named channel's value.

Notes:
The channel must have previously been added using the Sim.AvatarAddChannel function.

See also:
Sim.AvatarAddChannel, Sim.AvatarRemoveChannel, Sim.AvatarSetChannel


Sim.AvatarRemoveChannel

Remove the channel called name from the sim's avatar.

prototype Sim.AvatarRemoveChannel( hsim sim, string name);

Parameters:
sim : The sim.
name : The name of the channel.

Return value:
None.

Notes:
The name of the channel must match the name as defined in the Avatar's lightwave scene file.

See also:
Sim.AvatarAddChannel, Sim.AvatarChannelValue, Sim.AvatarSetChannel


Sim.AvatarSetChannel

Set the channel called name on a particular sim to the specified value.

prototype Sim.AvatarSetChannel( hsim sim, string name, float value);

Parameters:
sim : The sim.
name : The name of the channel.
value : The value to set for the channel.

Return value:
None.

Notes:
The channel must have previously been added using the Sim.AvatarAddChannel function.

See also:
Sim.AvatarAddChannel, Sim.AvatarChannelValue, Sim.AvatarRemoveChannel


Subsim

Subsims are the systems used by sims to perform their various game functions, such as engines, weapons and repair systems. This package facilitates the creation, manipulation and querying of subsim objects.

Note: Additional subsim related functions can be found in the Sim package.

Type definitions:

  • hsubsim

Functions:

  • Cast

  • Create

  • Destroy

  • OrientEueler
  • Place

  • Preload

  • Sim


Subsim.hsubsim

Handle to a subsim object - representing the simulation of a game object's internal systems.

hsubsim : hobject;

Notes:
This handle type is used to refer to the simulations of game objects internal systems.


Subsim.Cast

Casts a handle to an object to a handle to a subsim.

prototype hsim Subsim.Cast( hobject handle );

Parameters:
handle : The object handle to cast to a subsim handle.

Return value:
Returns a handle to a subsim.


Subsim.Create

Create a subsim from at template

prototype hsubsim Subsim.Create( string template, string name );

Parameters:
template : The name of the subsim template to create.
name : The name to assign to the newly created subsim.

Return value:
Returns a handle to the newly created subsim.

Notes:
The name of the subsim template is a resource url and should point to a suitable INI file.

See also:
Subsim.Destroy


Subsim.Destroy

Destroy the given subsim.

prototype hsubsim Subsim.Destroy( hsubsim subsim );

Parameters:
subsim : The handle of the subsim to destroy.

Return value:
None.

Notes:
Destroying a subsim automatically removes it from the sim that it is attached to.

See also:
Subsim.Create


Subsim.OrientateEuler

Orientates the subsim relative to its sim by the given Euler angles. This function will complain if the subsim hasn't been attached yet.

prototype Subsim.OrientateEuler( hsubsim subsim, float yaw, float pitch, float roll );

Parameters:
hsubsim : The handle of the subsim to place.
yaw : The yaw value
pitch : The pitch value
roll : The roll value

Return value:
None.

Notes:
The orientations are relative to the orientation of the subsim's parent sim.

See also:
Subsim.Place


Subsim.Place

Places the subsim at the given location on a sim. This function will complain if the subsim hasn't been attached yet.

prototype Subsim.Place( hsubsim subsim, float x, float y, float z );

Parameters:
hsubsim : The handle of the subsim to place.
x : The x coordinate.
y : The y coordinate.
z : The z coordinate.

Return value:
None.

Notes:
The coordinates are relative to the centre of the subsim's parent sim.

See also:
Subsim.OrientEuler


Subsim.Preload

Preload a subsim template and cache it for future use.

prototype Subsim.Preload( string template );

Parameters:
template : The name of the subsim template to cache.

Return value:
None

Notes:
The name of the subsim template is a resource url and should point to a suitable INI file.


Subsim.Sim

Return a handle to the sim that the subsim is attached to.

prototype hsim Subsim.Sim( hsubsim subsim );

Parameters:
subsim : The subsim to query.

Return value:
The sim the subsim is attached to, or none if the subsim is unattached.


Text

The Text package is used to add and remove localised text files, and to get localised text strings. See CSV Text files for more information.

Type definitions:

  • eFieldType

Functions:

  • Add
  • Remove
  • Field


Text.eFieldType

Ennumeration of field types currently available.

enum eFieldType{ FT_Text, FT_Wav };

Values:
FT_Text is linked to the first field in the CSV file after the key. FT_Wav is linked to the second field in the CSV file after the key.

See also:
Text.Field.


Text.Add

Loads a CSV file adding the data into an overall database used for localisation.

prototype Text.Add( string file_name );

Parameters:
file_name : The filename of the CSV file. Should not include extension and should be relative to a resource search path.

Return value:
None.

Notes:
The first field in the CSV is the key field and then the other fields are stored under this key.

See also:
Text.Remove.


Text.Field

Retrieve a string from the localised database.

prototype string Text.Field( string key,
                             eFieldType field );

Parameters:
key : The key into the localised database.
field : The field requested from this item in the database.

Return value:
Returns the localised string.

Notes:
Only those fields that are defined in eFieldType may be accessed.

See also:
Text.eFieldType.


Text.Remove

Removes the localised data that was added from this file.

prototype Text.Remove( string file_name );

Parameters:
file_name : File name of the CSV file. It should not include the extension and should be relative to a resource search path.

Return value:
None.

Notes:
This function works by opening the CSV file again, reading the keys, and removing them from the localisation database.

See also:
Text.Add.


I-War 2 packages
This page lists all the packages provided by I-War 2. These packages are intended for working with the gameplay objects and content specific to I-War 2.

Native code spaceflight packages

The following packages provide the tools for creating, querying and manipulating ships and other space objects. They are the primary tools for writing missions and story scripts. These packages are implemented in C++ and have been generally written by the programming team.
  • iAI
  • iBody
  • iDockport
  • iFaction
  • iHabitat
  • iLagrangePoint
  • iMapEntity
  • iRemotePilot
  • iRegion
  • iShip
  • iSim

Native code game packages

The following packages provide miscellaneous game functionality such as communications, scoring and cut-scenes.

  • iComms
  • iDirector
  • iMultiplay
  • iObjectives
  • iScore

Native code shell packages

The following packages provide programmability for the game shell, including the player base interface, the game front end, and the player's email system.
  • iCargo
  • iEmail
  • iGame
  • iHUD
  • iInventory
  • iLoadout
  • iMod
  • iOptions
  • iTrade

Pog Scripted Packages

Packages created in the Pog language have not been documented in this SDK. Please see the Header Reference section for information on the Pog scripted packages.


iAI

The iAI package gives access to the artificial intelligence of non-player pilots, by allowing you to give them orders.

Orders can be given to ships singly, or to a group of ships, and require that an AI pilot is installed in any ship that is to be given an order. See the iShip package for details of how to install an AI pilot.

If a ship has no orders, its default behaviour is to stay at rest.

Note: There are ways to order a ship's weapons separately without affecting its current order. See the iSim package for details.

Type definitions:

  • eOrderType
  • eAttackStyle

Functions:

  • AvoidanceRadius
  • ClearAutopilot
  • CurrentOrderName
  • CurrentOrderTarget
  • CurrentOrderType
  • ForceLPRoute
  • GiveApproachOrder
  • GiveA pproachOrderAdvanced
  • GiveApproachOrderNoDropOff
  • GiveAttackOrder
  • GiveDockOrder
  • GiveDockOrderWithDockport
  • GiveEscortOrder
  • GiveFleeOrder
  • GiveFormateOrder
  • GiveGenericAttackOrder
  • GiveReservedDockOrder
  • GiveSpecificAttackOrder
  • HasOrder
  • InnerMarkerRadius
  • IsOrderComplete
  • IsCapsuleJumpAccelerating
  • PurgeOrders
  • RemoveOrder
  • SetIgnoreFunction
  • SetFightFunction
  • SetFleeFunction
  • SetWimpyFunction


Global.eAttackStyle

Ennumeration describing an attack order's attack style.

enum eAttackStyle
{
    AS_TailBite,	// Try to get on an target's tail.
    AS_Strafe,	// Strafe the target using free-flight mode.
    AS_GunStation,	// Hold position and orientation while attacking using all available weapons.
    AS_FacingAttack,	// Hold position and face the target while attacking.
    AS_MissileBoat	// Stand off from the target and launch missiles.
};


Global.eOrderType

Ennumeration describing a type of order.

enum eOrderType
{
    OT_None,
    OT_Attack,
    OT_Formate,
    OT_Approach,
    OT_Dock,
    OT_Flee
};

Notes:
These represent the main order categories of I-War 2.


iAI.AvoidanceRadius

Returns the avoidance radius for a sim avoiding a given target.

prototype float iAI.AvoidanceRadius( hisim target, hisim us );

Parameters:
us : A handle to an AI sim.
target : A handle to another sim.

Return value:
The avoidance radius in metres.

See also:
iAI.InnerMarkerRadius


iAI.ClearAutopilot

Removes any current autopilot from the player ship.

prototype iAI.PurgeOrders();

Parameters:
None

Return value:
None

See also:
iAI.RemoveOrder, iAI.PurgeOrders


iAI.CurrentOrderName

Returns the order type being executed by the AI pilot of the given ship.

prototype string iAI.CurrentOrderName( hship ship );

Parameters:
ship : A handle to the AI ship to query.

Return value:
The name of the current order.

Notes:
Where a ship is invalid, has no AI pilot or the pilot has no current order, the empty string is returned.

See also:
CurrentOrderType, iAI.CurrentOrderTarget, iAI.HasOrder, iAI.IsOrderComplete


iAI.CurrentOrderTarget

Returns the target of the current order being executed by the AI pilot of the given ship.

prototype hisim iAI.CurrentOrderTarget( hship ship );

Parameters:
ship : A handle to the AI ship to query.

Return value:
A handle to the ship's current order target.

Notes:
A handle value of none will be returned if the ship does not have an order or a target.

See also:
eOrderType, iAI.CurrentOrderName, iAI.CurrentOrderType, iAI.HasOrder, iAI.IsOrderComplete


iAI.CurrentOrderType

Returns the order type being executed by the AI pilot of the given ship.

prototype eOrderType iAI.CurrentOrderType( hship ship );

Parameters:
ship : A handle to the AI ship to query.

Return value:
The current order type.

Notes:
Order type OT_None will be returned if the ship is invalid, does not have an AI pilot or the AI pilot has no current order.

See also:
eOrderType, iAI.CurrentOrderName, iAI.CurrentOrderTarget, iAI.HasOrder, iAI.IsOrderComplete


iAI.ForceLPRoute

This command is used to force an approach order to travel via two specified L-Points. This is useful when you wish to override the default L-Point routing, or to force an ship to travel via an L-Point rather than using LDS.

prototype iAI.ForceLPRoute( hship ship, hlagrangepoint lpoint_1, hlagrangepoint lpoint_2  );

Parameters:
ship : A handle to the ship you want to force the L-Point route onto.
lpoint_1 : The handle to the start l-point
dockport_2 : A handle to the destination l-point.

Return value:
None

Notes:
An order must already be active on the ship for this command to work.

See also:
iAI.IsCapsuleJumpAccelerating


iAI.GiveApproachOrder

Gives an approach order to a AI controlled ship or group of ships. If a group of ships is ordered to approach another group the first groups ships will pair up with ships in the other group.

As a default behaviour each AI controlled ship will approach their target until they are within 3 x the joint radius of both ship and target. (Incidentally it will aim for a position 2 x away and stop inside 3 x). They will do this once (before clearing the order) and will not worry about orientation.

prototype iAI.GiveApproachOrder( hobject us, hobject target );

Parameters:
us : A handle to an AI ship or group of ships the order is to be given to.
target : A handle to a sim or group of sims to approach.

Return value:
None

Notes:
No order will be given to a ship unless it has a pilot and that pilot is AI controlled.

See also:
iAI.GiveApproachOrderNoDropOff, iAI.GiveApproachOrderAdvanced


iAI.GiveApproachOrderAdvanced

This is an advanced version of the standard approach order, which allows the specification of approach radius, completion radius, and whether or not to use collision avoidance.

prototype iAI.GiveApproachOrderAdvanced( hobject us,
                     hobject target
                     float radius
                     float completion_radius
                     bool allow_avoidance );

Parameters:
us : A handle to an AI ship or group of ships the order is to be given to.
target : A handle to a sim or group of sims to approach.
radius : The distance from the target the approach order heads to.
completion_radius : The distance from the target when the order completes.
allow_avoidance : TRUE for avoidance turned on, FALSE for collision avoidance off.

Return value:
None

Notes:
No order will be given to a ship unless it has a pilot and that pilot is AI controlled.

See also:
iAI.GiveApproachOrder, iAI.GiveApproachOrderNoDropOff


iAI.GiveApproachOrderNoDropOff

This order is similar to the standard Approach order, but does not terminate when the approach target is reached. Unlike Formate, this order does not cause the ship(s) following the order to rotate to the same orientation as their target.

prototype iAI.GiveApproachOrderNoDropOff( hobject us, hobject target );

Parameters:
us : A handle to an AI ship or group of ships the order is to be given to.
target : A handle to a sim or group of sims to approach.

Return value:
None

Notes:
No order will be given to a ship unless it has a pilot and that pilot is AI controlled.

See also:
iAI.GiveApproachOrder, iAI.GiveApproachOrderAdvanced


iAI.GiveAttackOrder

Adds an attack order to the given AI controlled ship or group. The second parameter is the target sim or group of sims, and will be attacked relentlessly. The style of attack will be automatically chosen, depending on the attacker / target sim types. If the target(s) disappear off the sensor list the AI will wait for it to be reacquired.

prototype iAI.GiveAttackOrder( hobject us, hobject target );

Parameters:
us : A handle to the AI ship or group of ships the order is to be given to.
target : A handle to a sim or group of ships the AI ship(s) are to attack.

Return value:
None

Notes:
No order will be given to a ship unless it has a pilot and that pilot is AI controlled.

See also:
iAI.GiveSpecificAttackOrder, iAI.GiveGenericAttackOrder, iAI.GiveEscortOrder


iAI.GiveDockOrder

Gives a dock order to an AI controlled ship or group of ships.. The dock order approaches the given target heading for an outer waypoint. Once there it waits for an available docking port.

If it gets an available docking port it heads for its inner waypoint, a point off the upward normal of the docking port in question. Here it re-orientates its own port for direction (to ensure they oppose each other) and then for normal (to ensure the ships maintain the correct docking orientation). While this happens the ship slowly closes the distance. Finally the ship polls the target docking port for success at which stage it is removed.

prototype iAI.GiveDockOrder( hobject us, hobject target );

Parameters:
us : A handle to the AI ship or group of ships the order is to be given to.
target : A handle to a sim or group of sims the AI ship is to dock with.

Return value:
None

Notes:
The dockports on the ship(s) must be compatible with those of the target(s), and be enabled and free for the ship(s) to dock to.

See also:
iAI.GiveDockOrderWithDockport, iAI.GiveReservedDockOrder


iAI.GiveDockOrderWithDockport

This is similar to the GiveDockOrder command, except that the command allows you to force to sims to dock together using specific dockports. The function takes two arguments, a dockport on the docking sim, and a dockport from the sim it is docking to.

prototype iAI.GiveDockOrderWithDockport( hdockport dockport_1, hdockport dockport_2 );

Parameters:
dockport_1 : A handle to the dockport on the docking ship.
dockport_2 : A handle to the dockport on the target ship.

Return value:
None

Notes:
The dockports on the docking sim must be compatible with those of the target, and be enabled and free for the sims to dock to.

See also:
iAI.GiveDockOrder, iAI.GiveReservedDockOrder.


iAI.GiveEscortOrder

The GiveEscortOrder is essentially a combination of the Formate and GenericAttack orders.

The command formates a ship or group of ships with a target or group of targets. If any hostile vessels come within the specified radius, the escorting ships will break out of formation and attack. When there are no hostile vessels in range, the escort vessels will return to formation.

prototype iAI.GiveEscortOrder( hobject us,
                   hobject target,
                               float x,
                               float y,
                               float z,
                   float radius );

Parameters:
ship : A handle to the AI ship the order is to be given to.
sim : A handle to a sim the AI ship is to formate with.
x, y, z : A local offset vector for the target.
radius : The protection zone radius around the target.

Return value:
None

Notes:
No order will be given to a ship unless it has a pilot and that pilot is AI controlled. The vector is given in local co-ordinates.

See also:
GiveFormateOrder, GiveGenericAttackOrder


iAI.GiveFleeOrder

Gives an flee order to a AI controlled ship or group of ships. The ship(s) will attempt to run away from the target sim(s) until the order is removed.

prototype iAI.GiveFleeOrder( hobject us, hobject target );

Parameters:
us : A handle to an AI ship or group of ships the order is to be given to.
target : A handle to a sim or group of sims to flee from.

Return value:
None

Notes:
No order will be given to a ship unless it has a pilot and that pilot is AI controlled.

See also:
iAI.GiveAttackOrder


iAI.GiveFormateOrder

Gives a formate order to an AI controlled ship or group. The formate order will continue until removed. The ship or group of ships will head for the given local offset to their target, and will assume the orientation of the target object as they arrive.

prototype iAI.GiveFormateOrder( hship ship, hsim object, float x, float y, float z );

Parameters:
ship : A handle to the AI ship the order is to be given to.
sim : A handle to a sim the AI ship is to formate with.
x, y, z : A local offset vector for the target.

Return value:
None

Notes:
No order will be given to a ship unless it has a pilot and that pilot is AI controlled. The vector is given in local co-ordinates.

See also:
iAI.GiveEscortOrder


iAI.GiveGenericAttackOrder

Adds a generic attack order to the given AI controlled ship or group.

Generic attack orders cause the ship(s) to attack the closest hostile vessels (as defined by the feelings of the ship(s) towards the target sim(s) factions) with the greatest threat rating.

Generic attack orders continue until removed. If there are no targets the ship(s) will hold position until new targets appear.

prototype iAI.GiveGenericAttackOrder( hobject us );

Parameters:
us : A handle to the AI ship or group of ships the order is to be given to.

Return value:
None

Notes:
No order will be given to a ship unless it has a pilot and that pilot is AI controlled.

See also:
iAI.GiveAttackOrder, iAI.GiveSpecificAttackOrder, iAI.GiveEscortOrder


iAI.GiveReservedDockOrder

This is similar to the GiveDockOrder command, except that it attempts to reserve the dockports of the docking vessels before giving the order. This prevents any other sims docking to those dockports, so the docking can proceed without interference.

prototype iAI.GiveReservedDockOrder( hobject us, hobject target );

Parameters:
us : A handle to the AI ship or groupof ships the order is to be given to.
target : A handle to a sim or group of sims the AI ship is to dock with.

Return value:
None

Notes:
The dockports on the ship(s) must be compatible with those of the target(s), and be enabled and free for the ship(s) to dock to.

See also:
GiveDockOrderWithDockport, GiveReservedDockOrder


iAI.GiveSpecificAttackOrder

This is an advanced version of GiveAttackOrder, that allows you to specify the attack style used.

prototype iAI.GiveSpecificAttackOrder( hobject us, hobject target, int attack_style );

Parameters:
us : A handle to the AI ship or group of ships the order is to be given to.
target : A handle to a sim or group of ships the AI ship(s) are to attack.
attack_style : A integer defining which attack style to use.

Return value:
None

Notes:
No order will be given to a ship unless it has a pilot and that pilot is AI controlled.
The attack styles are defined in the enum eAttackStyle.

See also:
iAI.GiveAttackOrder, iAI.GiveGenericAttackOrder, iAI.GiveEscortOrder.


iAI.HasOrder

Returns true if the ship has at least one order.

prototype bool iAI.HasOrder( hship ship );

Parameters:
ship : A handle to the AI ship to be checked.

Return value:
Returns true if the ship has at least one order. Returns false if the ship has no orders or is not AI controlled.

Notes:

See also:
iAI.CurrentOrderName, iAI.CurrentOrderTarget, iAI.CurrentOrderType, iAI.IsOrderComplete


iAI.InnerMarkerRadius

Returns the inner marker radius for a sim for the approach / formate escort orders.

prototype float iAI.InnerMarkerRadius( hisim target, hisim us );

Parameters:
us : A handle to an AI sim.
target : A handle to another sim.

Return value:
The inner marker radius in metres.

See also:
iAI.AvoidanceRadius


iAI.IsOrderComplete

Returns true if the ship or group of ships current order is flagged as completed.

prototype bool iAI.IsOrderComplete( hobject ship_or_group );

Parameters:
ship_or_group : A handle to the AI ship or group of ships to be checked.

Return value:
Returns true if the ship's or group of ships order has been completed. Returns false otherwise.

See also:
iAI.CurrentOrderName, iAI.CurrentOrderTarget, iAI.CurrentOrderType, iAI.HasOrder


iAI.IsCapsuleJumpAccelerating

Returns true if the ship is accelerating for a capsule jump.

prototype bool iAI.IsCapsuleJumpAccelerating( hship ship );

Parameters:
ship : A handle to the AI ship to be checked.

Return value:
Returns true if the ship is accelerating for a capsule jump, false otherwise.

Notes:

See also:
iAI.ForceLPRoute


iAI.PurgeOrders

Purges all orders from the given AI controlled ship or group. If no order is being run then this function simply does nothing. If an order is being run it is removed from the order list and the agents operating are cleared.

Note: Due to the changes to the AI system during development, this command supersedes the RemoveOrder command, and should be used in preference.

prototype iAI.PurgeOrders( hobobject ship_or_group );

Parameters:
ship_or_group : A handle to the AI ship or group of ships the orders are to be purged from.

Return value:
None

See also:
iAI.RemoveOrder, iAI.ClearAutopilot


iAI.RemoveOrder

Removes the current order from the given AI controlled ship or group. If no order is being run then this function simply does nothing. If an order is being run it is removed from the order list and the agents operating are cleared.

Note: Due to the changes to the AI system during development, this command has largely been superseded by the PurgeOrders command.

prototype iAI.RemoveOrder( hobobject ship_or_group );

Parameters:
ship_or_group : A handle to the AI ship or group of ships the order is to be removed from.

Return value:
None

See also:
iAI.PurgeOrders


iAI.SetIgnoreFunction

Sets the AI ship's ignore function.

prototype iAI.SetIgnoreFunction( hship ship, string function );

Parameters:
ship : A handle to the AI ship.
function : The ignore function to use.

Return value:
None.

Notes:
This overrides the ignore function set up when the AI pilot was originally installed.

See also:
iAI.SetFightFunction, iAI.SetFleeFunction, iAI.SetWimpyFunction


iAI.SetFightFunction

Sets the AI ship's fight function.

prototype iAI.SetFightFunction( hship ship, string function );

Parameters:
ship : A handle to the AI ship.
function : The fight function to use.

Return value:
None.

Notes:
This overrides the fight function set up when the AI pilot was originally installed.

See also:
iAI.SetFleeFunction, iAI.SetIgnoreFunction, iAI.SetWimpyFunction


iAI.SetFleeFunction

Sets the AI ship's flee function.

prototype iAI.SetFleeFunction( hship ship, string function );

Parameters:
ship : A handle to the AI ship.
function : The flee function to use.

Return value:
None.

Notes:
This overrides the flee function set up when the AI pilot was originally installed.

See also:
iAI.SetFightFunction, iAI.SetIgnoreFunction, iAI.SetWimpyFunction


iAI.SetWimpyFunction

Sets the AI ship's wimpy function.

prototype iAI.SetWimpyFunction( hship ship, string function );

Parameters:
ship : A handle to the AI ship.
function : The wimpy function to use.

Return value:
None.

Notes:
This overrides the wimpy function set up when the AI pilot was originally installed.

See also:
iAI.SetFightFunction, iAI.SetFleeFunction, iAI.SetIgnoreFunction


iBody

This package governs the use of celestial bodies.

Type definitions:

  • hbody
  • IeBodyType

Functions:

  • Cast
  • Type
  • HabitatsAroundBody
  • OrbitingBodies
  • FindByName
  • Nearest
  • Random
  • FilterOnType

Notes:

Non-body specific functions that can be used on bodies can be found in iMapEntity.


iBody.hbody

A handle to a celestial body object.

hbody : hmapentity;

See also:
iMapEntity, iMapEntity.hmapentity.


iBody.IeBodyType

This enumeration is used for the type of celestial body.

enum IeBodyType
{
    BT_SystemCentre = 0,
    BT_Star = 1,
    BT_Planet = 2,
    BT_Moon = 3,
    BT_GasGiant = 4,
    BT_Asteroid = 5,
    BT_DeadGasGiantCore = 6,
    BT_AsteroidBelt = 7,
    BT_Nebula = 8,
    BT_Invalid = 9
};

Notes:
The declaration of this enumeration can be found in MapEnumerations.h.

See also:
iHabitat.IeHabitatType, iBody.Type, iBody.FilterOnType.


iBody.Cast

Cast a handle up to a handle to celestial body.

prototype hbody iBody.Cast( hobject handle );

Parameters:
handle : The handle to cast.

Return value:
A handle to a body.

Notes:
If the object handle is invalid or the object is not a celestial body then a null handle is returned.


iBody.FilterOnType

Filter out celestial bodies which do not match a given body type.

prototype set iBody.FilterOnType( set bodies,
                                  IeBodyType type );

Parameters:
bodies : The set of bodies to filter.
type : The body type to filter on.

Return value:
Returns a set of those bodies from the given set which match the given type.

See also:
iMapEntity.SystemBodies, iBody.OrbitingBodies, iBody.Type, iBody.IeBodyType.


iBody.FindByName

Finds a celestial body matching a given name.

prototype hbody iBody.FindByName( string name );

Parameters:
name : The name to search for.

Return value:
A handle to a body matching the given name, or a null handle if the search failed.

Notes:
This function will only return the first celestial body with the given name.


iBody.HabitatsAroundBody

Get a set of habitats around a given body.

prototype set iBody.HabitatsAroundBody( hbody body );

Parameters:
body : The body to query.

Return value:
A set of all habitats around the given body.

Notes:
This function will return all habitats on the surface of or in orbit around the given body. It will include habitats around any of these orbiting habitats. It will not include habitats around bodies orbiting the body.

See also:
iBody.OrbitingBodies.


iBody.Nearest

Of a set of celestial bodies, find the closest to a given sim.

prototype hbody iBody.Nearest( set bodies,
                               hsim sim );

Parameters:
bodies : A set of handles to bodies.
sim : The sim to find the closest body to.

Return value:
The nearest body to the given sim.

See also:
iMapEntity.SystemBodies, iBody.FilterOnType, iBody.Random.


iBody.OrbitingBodies

Returns a set of celestial bodies orbiting a given body.

prototype set iBody.OrbitingBodies( hbody body );

Parameters:
body : The body to query.

Return value:
A set of all bodies orbiting the given body.

Notes:
This function will include any child bodies of those orbiting the given body.

The body itself is excluded.

See also:
iBody.HabitatsAroundBody.


iBody.Random

Pick a random body from a given set of bodies.

prototype hbody iBody.Random( set bodies );

Parameters:
bodies : A set of handles to bodies.

Return value:
A random body in the given set.

See also:
iMapEntity.SystemBodies, iBody.FilterOnType, iBody.Nearest.


iBody.Type

Determine the type of a celestial body.

prototype IeBodyType iBody.Type( hbody body );

Parameters:
body : The body to query.

Return value:
The body type of the given body as a member of the IeBodyType enumerator.

See also:
iBody.IeBodyType.


iDockport

This package deals with accessing and manipulating dockports, a special class of subsim.

Type definitions:

  • hdockport
  • eDockportStatus
  • eDockportType

Functions:

  • Count
  • Disable
  • Dock
  • DockportsOfType
  • DockportsCompatibleWith
  • E nable
  • IsDisabled
  • IsType
  • SetType
  • Status

Notes:

Dockports are derived from Subsims, so Subsim functions can also be used to find and manipulate dockports.


iDockport.hdockport

I-War 2 dockport handle.

hdockport : hsubsim;


iDirector.eDockportStatus

This enumeration is used for the different dockport states..

enum eDockportStatus
{

    DS_Invalid,	// Default return value for invalid dockport handles
    DS_Free,		// The dockport is free
    DS_Reserved,	// Reserved for a docking ship
    DS_Used,		// Occupied by a docked object
    DS_Any		// Any status, including Invalid
};

See Also:
iDirector.eDockportType


iDirector.eDockportType

This enumeration is used for the different dockport types.

enum eDockportType
{
    DT_All,			// All ports including those disabled
    DT_Disabled,		// Only disabled ports
    DT_Cargo,			// Cargo pod ports
    DT_CargoFreightOnly,	// The cargo freighter port
    DT_Freight,		// Freight ports (1 per station - the spewer main dockport)
    DT_Fuel,			// Fuel ports (usually 1 per station - refuel ports)
    DT_Ship,			// General ship / docking ports (was T_CommandSection)
    DT_General,		// General ports (including cargo)
    DT_Universal		// Universal (similar to the above)
};

See Also:
iDirector.eDockportStatus


iDockport.Count

Returns a count of the number of free dockports on a given sim of the given mask

prototype prototype int iDockport.Count( hisim sim, eDockportType type, eDockportStatus status );

Parameters:
sim : The sim to count the dockports on.
type : The type of dockport to count.
status : The dockport status required.

 Return value:
An int showing the number of dockports found.


iDockport.Disable

Disable the given dockport.

prototype iDockport.Disable( hdockport dockport );

Parameters:
dockport : The dockport to disable

 Return value:
None

See also:
iDockport.Enable


iDockport.Dock

Docks two sims together using the specified dockports.

prototype bool iDockport.Dock( hdockport dockport_1, hdockport dockport_2 );

Parameters:
dockport_1 : The dockport on the first sim.
dockport_2 : The dockport on the second sim.

 Return value:
TRUE if the docking was successful. FALSE otherwise.

Notes:
Both dockports must be free and unreserved. This function can still fail if either dockport is shutdown in which case it returns false.

See also:
iSim.Dock


iDockport.DockportsCompatibleWith

Returns all dockports on a sim that are compatible with the specified dockport type and status.

prototype set iDockport.DockportsCompatibleWith( hisim sim,
                         eDockportType type,
                         eDockportStatus status );

Parameters:
sim : The sim to find the dockports on.
type : The type of dockport.
status : The dockport status.

 Return value:
A set containing the handles of the found dockports.

See also:
iDockport.DockportsOfType


iDockport.DockportsOfType

Returns all matching dockports as a set.

prototype set iDockport.DockportsOfType( hisim sim,
                     eDockportType type,
                     eDockportStatus status );

Parameters:
sim : The sim to find the dockports on.
type : The type of dockport to find.
status : The dockport status required.

 Return value:
A set containing the handles of the matched dockports.

See also:
iDockport.DockportsCompatibleWith


iDockport.Enable

Enable the given dockport.

prototype iDockport.Enable( hdockport dockport );

Parameters:
dockport : The dockport to enable

 Return value:
None

See also:
iDockport.Disable


iDockport.IsDisabled

Check if a dockport is disabled.

prototype bool iDockport.IsDisabled( hdockport dockport );

Parameters:
dockport : The dockport to check

 Return value:
TRUE if the dockport is disabled, FALSE otherwise.

See also:
iDockport.Disable


iDockport.IsType

Check if a dockport is of a specified type.

prototype bool iDockport.IsType( hdockport dockport, eDockportType type );

Parameters:
dockport : The dockport to check
type : The type to check

 Return value:
TRUE if the dockport is of the specified type, FALSE otherwise.

See also:
iDockport.SetType


iDockport.SetType

Change the given dockport's type.

prototype iDockport.SetType( hdockport dockport, eDockportType type );

Parameters:
dockport : The dockport to set
dockport : The type to set

 Return value:
None

See also:
iDockport.IsType


iDockport.Status

Returns a the dockport's status, as defined in eDockportStatus.

prototype eDockportStatus iDockport.Status( hdockport dockport );

Parameters:
dockport : The dockport.

 Return value:
An enum showing the dockport's status.


iFaction

Faction control package. Allows the creation of factions and the accessing and setting of feelings towards other factions.

Type definitions:

  • hfaction
  • eFeelingType

Functions:

  • All
  • Allegiance
  • Cast
  • Create
  • Find
  • Feeling
  • FeelingLevel
  • FeelingType
  • IncrementFeeling
  • Name
  • SetFeeling


iFaction.hfaction

Faction object handle.

hfaction : hobject;


iFaction.eFeelingType

Ennumerates types of feeling between factions.

enum eFeelingType{ FT_Hate, FT_Dislike, FT_Neutral, FT_Like, FT_Love };

Values:
The different types of feeling are related to a range of feeling level.

Notes:
The range relating to each type is set in the game configuration file. It is specified by the boundaries between types as follows:

[FactionLevels]
Hate-Dislike = -0.6
Dislike-Neutral = -0.2
Neutral-Like = 0.2
Like-Love = 0.6


iFaction.All

Retrieve a list of all the faction handles.

prototype list iFaction.All( );

Parameters:
None.

Return value:
Returns a list of all the faction handles.

See also:
iFaction.Find.


iFaction.Allegiance

Return the allegiance of the faction, as a member of the IeAllegiance enumeration.

prototype IeAllegiance iFaction.Allegiance( hfaction faction );

Parameters:
faction : The faction to query.

Return value:
The allegiance of the faction, as a member of the ieAllegiance enumeration.

Notes:
The definition of the IeAlleigance enumeration can be found in MapEnumerations.h.

See also:
iFaction.Create.


iFaction.Cast

Casts an hobject handle to an hfaction handle.

prototype hfaction iFaction.Cast( hobject the_handle );

Parameters:
faction_handle : The handle to be cast to an hfaction handle.

Return value:
Returns an hfaction handle from the hobject handle. Returns none if the object was not a faction.

Notes:
This function can be used to cast handles taken from a list or set into an hfaction handle.


iFaction.Create

Creates a new faction.

prototype hfaction iFaction.Create( string name,
                                    string prefix,
                    IeAllegiance allegiance );

Parameters:
name : The name of the new faction.
prefix : The faction prefix, a three letter shortening.
allegiance : The faction allegiance, a member of the IeAllegiance enumeration.

Return value:
Returns a handle to the new faction.

Notes:
Factions cannot be destroyed.

The definition of the IeAllegiance enumeration can be found in MapEnumerations.h.

See also:
iFaction.Allegiance.


iFaction.Feeling

Find the feeling of a faction towards another faction.

prototype float iFaction.Feeling( hfaction feeler,
                                  hfaction feelee );

Parameters:
feeler : The faction who's feelings are being interrogated.
feelee : The faction towards which we are finding a feeling level.

Return value:
Returns a feeling level between -1.0 and 1.0.

Notes:
If either factions are invalid the the function returns 0.

See also:
iFaction.FeelingType, iFaction.SetFeeling, iFaction.IncrementFeeling.


iFaction.FeelingLevel

Get the mid-point value of the range covered by this feeling type.

prototype float MyPackage.MyFunction( eFeelingType feeling );

Parameters:
feeling : The feeling type to convert to a feeling value.

Return value:
Returns the feeling value that corresponds with the mid-point of the feeling types range.

Notes:
Feeling values are in the range -1.0 to 1.0.

See also:
iFaction.FeelingType.


iFaction.FeelingType

Convert the feeling level into an enumerated feeling type.

prototype eFeelingType iFaction.FeelingType( float level );

Parameters:
level : The feeling level in the range of -1.0 to 1.0.

Return value:
Returns the feeling type.

See also:
iFaction.eFeelingType, iFaction.FeelingLevel.


iFaction.Find

Retrieves a faction handle from the name.

prototype hfaction iFaction.Find( string name );

Parameters:
name : The name of the faction to find.

Return value:
Returns the handle to the faction or none if the faction does not exist.

See also:
iFaction.All.


iFaction.IncrementFeeling

Increment the feeling of a faction towards another faction.

prototype iFaction.IncrementFaction( hfaction feeler,
                                     hfaction feelee,
                                     float level_increase );

Parameters:
feeler : The faction whose feeling is to be changed.
feelee : The faction to which the feeling towards will be increased.
level_increase : The level by which to change the feeling.

Return value:
None.

Notes:
A negative increase in level will decrease the feeling.

See also:
iFaction.SetFeeling.


iFaction.Name

Retrieves a faction name from the handle.

prototype string iFaction.Name( hfaction faction );

Parameters:
faction : The name of the faction to find the name for.

Return value:
Returns a string containing the faction name key.


iFaction.SetFeeling

Set the feeling of a faction towards another faction.

prototype iFaction.SetFeeling( hfaction feeler,
                               hfaction feelee,
                               float level );

Parameters:
feeler : The faction whose feelings are to be changed.
feelee : The faction to which the feeling towards is to be changed.
level : The level of feeling

Return value:
None

Notes:
The level of feeling should lie in the range of -1.0 to 1.0.

See also:
iFaction.IncrementFeeling.


iHabitat

A package governing man-made habitats such as settlements and space stations.

Type definitions:

  • hhabitat
  • iehabitattype

Functions:

General

  • Allegiance
  • Cast
  • CastIntToHabitatType
  • FilterOnAllegiance
  • FilterOnType
  • FilterOrbiting
  • FindByName
  • IsOrbiting
  • Nearest
  • Random
  • Type

Population

These functions deal with the populations 'living' on the stations. The only one currently used in-game is the Population command, which is used to determine the amount of cargo being shipped to and from the habitats.

  • Corporates
  • Exiles
  • Government
  • Independents
  • Military
  • Population
  • Society
  • Transient
  • Underworld

Pod Spewer

A pod spewer is a special module used for loading and unloading cargo.

  • HasSpewer
  • HasSpewerSlotFree
  • Spew

Arming

These functions deal with arming stations.

  • SetArmed
  • SetArmedWithTarget
  • SetReactiveFunction


iHabitat.hhabitat

A handle for man-made habitats - settlements and space stations.

hhabitat : hmapentity;

See also:
iMapEntity, iMapEntity.hmapentity.


iHabitat.ieHabitatType

This enumeration is used for the type of a habitat.

enum IeHabitatType
{
    HT_Invalid = 0,
    HT_Disused = 1,
    HT_WaterMine = 2,
    HT_OrganicsMine = 3,
    HT_InorganicsMine = 4,
    HT_BiomassMine = 5,
    HT_CommonMetalsMine = 6,
    HT_RareMetalsMine = 7,
    HT_ExoticMetalsMine = 8,
    HT_RadioactivesMine = 9,
    HT_FusionableGasesMine = 10,
    HT_WaterProcessingPlant = 11,
    HT_OrganicsProcessingPlant = 12,
    HT_InorganicsProcessingPlant = 13,
    HT_BiomassProcessingPlant = 14,
    HT_CommonMetalsProcessingPlant = 15,
    HT_RareMetalsProcessingPlant = 16,
    HT_ExoticMetalsProcessingPlant = 17,
    HT_RadioactivesProcessingPlant = 18,
    HT_FusionableGasesProcessingPlant = 19,
    HT_NeutroniumProcessingPlant = 20,
    HT_Shipyard = 21,
    HT_HeavyManufacturingPlant = 22,
    HT_BiologicalManufacturingPlant = 23,
    HT_WetwareManufacturingPlant = 24,
    HT_HiTechManufacturingPlant = 25,
    HT_ElectronicsManufacturingPlant = 26,
    HT_WeaponsManufacturingPlant = 27,
    HT_PharmaceuticalsManufacturingPlant = 28,
    HT_PlasticsManufacturingPlant = 29,
    HT_FusionReactorsManufacturingPlant = 30,
    HT_EnergyCellsManufacturingPlant = 31,
    HT_StationFabricationManufacturingPlant = 32,
    HT_LuxuriesManufacturingPlant = 33,
    HT_TerraformingStation = 34,
    HT_BioBomber = 35,
    HT_Waystation = 36,
    HT_RepairStation = 37,
    HT_OreTransferStation = 38,
    HT_ResearchAndDevelopmentLab = 39,
    HT_ResearchStation = 40,
    HT_MedicalResearchCentre = 41,
    HT_BlackBudgetResearchStation = 42,
    HT_SensitiveResearchStation = 43,
    HT_FinancialCentre = 44,
    HT_RegionalHQ = 45,
    HT_Villa = 46,
    HT_CentralHQ = 47,
    HT_AgriculturalSettlement = 48,
    HT_Resort = 49,
    HT_LuxuryResort = 50,
    HT_MedicalFacility = 51,
    HT_LeisureComplex = 52,
    HT_NeutroniumMine = 53,
    HT_SecurityStation = 54,
    HT_Fortress = 55,
    HT_HighSecurityPrison = 56,
    HT_LowSecurityPrison = 57,
    HT_HardLabourPrison = 58,
    HT_Homestead = 59,
    HT_MercenaryBase = 60,
    HT_TradingPost = 61,
    HT_Warehousing = 62,
    HT_BlackMarket = 63,
    HT_DryDock = 64,
    HT_DockingStation = 65,
    HT_EntertainmentStation = 66,
    HT_Settlement = 67,
    HT_PoliceBase = 68,
    HT_PoliceOutpost = 69,
    HT_SystemDefenceStation = 70,
    HT_SystemDefenceDock = 71,
    HT_NavalAcademy = 72,
    HT_NavalTrainingBase = 73,
    HT_Outpost = 74,
    HT_Base = 75,
    HT_RepairDock = 76,
    HT_MarineBarracks = 78,
    HT_PerimeterDefences = 79,
    HT_NavalTestingSite = 80,
    HT_NavalResearchFacility = 81,
    HT_JumpFortress = 82,
    HT_SupplyDepot = 84,
    HT_DefenceStation = 85,
    HT_STCPost = 86,
    HT_STCHQ = 87,
    HT_FTLArray = 88,
    HT_FTLInterchange = 89,
    HT_STLTranceiver = 90,
    HT_STLInterchange = 91,
    HT_PlanetaryAdministration = 92,
    HT_SystemAdministration = 93,
    HT_ClusterAdministration = 94,
    HT_RegionalDepartment = 95,
    HT_University = 96,
    HT_Ark = 97,
    HT_Garden = 98,
    HT_Asylum = 99,
    HT_Hospice = 100,
    HT_PirateBase = 101,
    HT_PirateCove = 102,
    HT_PirateOutpost = 103,
    HT_GangsterHideout = 104,
    HT_ViceDen = 105,
    HT_Casino = 106,
    HT_CollectiveSettlement = 107,
    HT_Hermitage = 108,
    HT_ReligiousCentre = 109,
    HT_MadScientistLab = 110,
    HT_Hideout = 111,
    HT_Habitat = 112,
    HT_Junkyard = 113,
    HT_BoxTown = 114,
    HT_AsteroidSculptures = 115,
    HT_PlayerBase = 116,
    HT_GunstarArray = 117,
    HT_JumpAccelerator = 118,
    HT_HoffersGap = 119,
    HT_HoffersHeel = 120,
    HT_Beanstalk = 121,
    HT_TransferStation = 122

};

Notes:
The declaration of this enumeration can be found in MapEnumerations.h.

See also:
iBody.IeBodyType, iHabitat.Type, iHabitat.FilterOnType.


iHabitat.Allegiance

Find the allegiance of a given habitat.

prototype IeAllegiance iHabitat.Allegiance( hhabitat habitat );

Parameters:
habitat : The habitat to query.

Return value:
The allegiance of the given habitat.

Notes:
The declaration of the IeAllegiance enumeration can be found in MapEnumerations.h.

See also:
iHabitat.FilterOnAllegiance.


iHabitat.Cast

Casts a handle up to a habitat handle.

prototype hhabitat iHabitat.Cast( hobject handle );

Parameters:
handle : The handle to cast up.

Return value:
A handle to a habitat, or null.

Notes:
If the given handle is not valid or if the object is not a habitat then a null handle is returned.


iHabitat.CastIntToHabitatType

Cast an integer value up to a habitat type.

prototype IeHabitatType iHabitat.CastIntToHabitatType( int value );

Parameters:
value : The value to cast up to a habitat type.

Return value:
A member of the IeHabitatType enumeration.

Notes:
The definition of the IeHabitatType enumeration can be found in MapEnumerations.h.

See also:
iHabitatType.IeHabitatType.


iHabitat.FilterOnAllegiance

Given a set of habitats, return a set of those habitats with a given allegiance.

prototype set iHabitat.FilterOnAllegiance( set habitats,
                                           IeAllegiance allegiance );

Parameters:
habitats : The set of habitats to filter.
allegiance : The allegiance to filter on.

Return value:
A set of those members of the given set with the given allegiance.

See also:
iMapEntity.SystemHabitats, iHabitat.Allegiance.


iHabitat.FilterOnType

Filter out habitats which do not match a given habitat type.

prototype set iHabitat.FilterOnType( set habitats,
                                     IeHabitatType type );

Parameters:
habitats : The set of habitats to filter.
type : The habitat type to filter on.

Return value:
Returns a set of those habitats from the given set which match the given type.

See also:
iMapEntity.SystemHabitats, iHabitat.Type, iHabitat.IeHabitatType.


iHabitat.FilterOrbiting

Filter out habitats which are not orbiting.

prototype set iHabitat.FilterOrbiting( set habitats );

Parameters:
habitats : The set of habitats to filter.

Return value:
Returns a set of those habitats from the given set which are orbiting their parent bodies.

Notes:
Non-orbiting habitats are no longer used in the game, so this command is effectively redundant.

See also:
iMapEntity.SystemHabitats, iHabitat.Type, iHabitat.IeHabitatType.


iHabitat.FindByName

Finds a habitat matching a given name.

prototype hhabitat iHabitat.FindByName( string name );

Parameters:
name : The name to search for.

Return value:
A handle to a habitat matching the given name, or a null handle if the search failed.

Notes:
This function will only return the first habitat with the given name.


iHabitat.IsOrbiting

Check if a habitat is orbiting or surfaced based.

prototype bool iHabitat.IsOrbiting( hhabitat habitat );

Parameters:
habitat : The habitat to check.

Return value:
TRUE if the habitat is orbiting, FALSE otherwise.

Notes:
Non-orbiting habitats are no longer used in the game, so this command is effectively redundant.

See also:
iHabitat.FilterOrbiting


iHabitat.Nearest

Of a set of habitats, find the closest to a given sim.

prototype hhabitat iHabitat.Nearest( set habitats,
                                     hsim sim );

Parameters:
habitats : A set of handles to habitats.
sim : The sim to find the closest body to.

Return value:
The nearest habitat to the given sim.

See also:
iMapEntity.SystemHabitats, iHabitat.FilterOnType, iHabitat.Random.


iHabitat.Random

Pick a random habitat from a given set of habitats.

prototype hhabitat iHabitat.Random( set habitats );

Parameters:
habitats : A set of handles to habitats.

Return value:
A random habitat in the given set.

See also:
iMapEntity.SystemHabitats, iHabitat.FilterOnType, iHabitat.Nearest.


iHabitat.Type

Determine the type of a habitat.

prototype IeHabitatType iHabitat.Type( hhabitat habitat );

Parameters:
habitat : The habitat to query.

Return value:
The habitat type of the given habitat as a member of the IeHabitatType enumerator.

See also:
iHabitat.IeHabitatType.


iHabitat.Corporates

Get the corporates population of a given habitat.

prototype int iHabitat.Corporates( hhabitat habitat );

Parameters:
habitat : The habitat to inspect.

Return value:
The corporate population of the given entity.

Notes:
This function returns the number of corporates on the given habitat.

See also:
iHabitat.Population, iHabitat.Independents, iHabitat.Exiles, iHabitat.Military, iHabitat.Government, iHabitat.Underworld, iHabitat.Transient, iHabitat.Society.


iHabitat.Exiles

Get the exile population of a given habitat.

prototype int iHabitat.Exiles( hhabitat habitat );

Parameters:
habitat : The habitat to inspect.

Return value:
The exile population of the given entity.

Notes:
This function returns the number of exiles on the given habitat.

See also:
iHabitat.Population, iHabitat.Corporates, iHabitat.Independents, iHabitat.Military, iHabitat.Government, iHabitat.Underworld, iHabitat.Transient, iHabitat.Society.


iHabitat.Government

Get the government population of a given habitat.

prototype int iHabitat.Government( hhabitat habitat );

Parameters:
habitat : The habitat to inspect.

Return value:
The government population of the given entity.

Notes:
This function returns the number of government on the given habitat.

See also:
iHabitat.Population, iHabitat.Corporates, iHabitat.Independents, iHabitat.Exiles, iHabitat.Military, iHabitat.Underworld, iHabitat.Transient, iHabitat.Society.


iHabitat.Independents

Get the independent population of a given habitat.

prototype int iHabitat.Independents( hhabitat habitat );

Parameters:
habitat : The habitat to inspect.

Return value:
The independent population of the given entity.

Notes:
This function returns the number of corporates on the given habitat.

See also:
iHabitat.Population, iHabitat.Corporates, iHabitat.Exiles, iHabitat.Military, iHabitat.Government, iHabitat.Underworld, iHabitat.Transient, iHabitat.Society.


iHabitat.Military

Get the military population of a given habitat.

prototype int iHabitat.Military( hhabitat habitat );

Parameters:
habitat : The habitat to inspect.

Return value:
The military population of the given entity.

Notes:
This function returns the number of military on the given habitat.

See also:
iHabitat.Population, iHabitat.Corporates, iHabitat.Independents, iHabitat.Exiles, iHabitat.Government, iHabitat.Underworld, iHabitat.Transient, iHabitat.Society.


iHabitat.Population

Get the total population of a habitat.

prototype int iHabitat.Population( hhabitat habitat );

Parameters:
habitat : The habitat to inspect.

Return value:
The total population of the given entity.

Notes:
This function returns the total population - i.e. the sum of all the different demographics groups.

See also:
iHabitat.Corporates, iHabitat.Independents, iHabitat.Exiles, iHabitat.Military, iHabitat.Government, iHabitat.Underworld, iHabitat.Transient, iHabitat.Society.


iHabitat.Society

Get the society population of a given habitat.

prototype int iHabitat.Society( hhabitat habitat );

Parameters:
habitat : The habitat to inspect.

Return value:
The society population of the given entity.

Notes:
This function returns the number of society on the given habitat.

See also:
iHabitat.Population, iHabitat.Corporates, iHabitat.Independents, iHabitat.Exiles, iHabitat.Military, iHabitat.Government, iHabitat.Underworld, iHabitat.Transient.


iHabitat.Transient

Get the transient population of a given habitat.

prototype int iHabitat.Transient( hhabitat habitat );

Parameters:
habitat : The habitat to inspect.

Return value:
The transient population of the given entity.

Notes:
This function returns the number of transients on the given habitat.

See also:
iHabitat.Population, iHabitat.Corporates, iHabitat.Independents, iHabitat.Exiles, iHabitat.Military, iHabitat.Government, iHabitat.Underworld, iHabitat.Society.


iHabitat.Underworld

Get the underworld population of a given habitat.

prototype int iHabitat.Underworld( hhabitat habitat );

Parameters:
habitat : The habitat to inspect.

Return value:
The underworld population of the given entity.

Notes:
This function returns the number of underworld on the given habitat.

See also:
iHabitat.Population, iHabitat.Corporates, iHabitat.Independents, iHabitat.Exiles, iHabitat.Military, iHabitat.Government, iHabitat.Transient, iHabitat.Society.


iHabitat.HasSpewer

Check if a habitat has a cargo pod loading / unloading module ( known as a pod spewer ).

prototype bool iHabitat.HasSpewer( hhabitat habitat );

Parameters:
habitat : The habitat to check.

Return value:
TRUE if the habitat has a pod spewer, FALSE otherwise.

See also:
iHabitat.HasSpewerSlotFree, iHabitat.Spew


iHabitat.HasSpewerSlotFree

Check if a habitat has a free slot on its cargo pod loading / unloading module ( known as a pod spewer ).

prototype bool iHabitat.HasSpewerSlotFree( hhabitat habitat );

Parameters:
habitat : The habitat to check.

Return value:
TRUE if the habitat has a pod spewer slot free, FALSE otherwise.

See also:
iHabitat.HasSpewer, iHabitat.Spew


iHabitat.Spew

Unload (Spew) a pod from a pod spewer.

prototype iHabitat.Spewer( hhabitat habitat, hsim cargo_pod );

Parameters:
habitat : The habitat to spew a pod from.
hsim : The pod to spew.

Return value:
None.

See also:
iHabitat.HasSpewer, iHabitat.HasSpewerSlotFree


iHabitat.SetArmed

Arms or disarms a station.

prototype iHabitat.SetArmed( hhabitat habitat, bool armed );

Parameters:
 habitat : The habitat to arm / disarm.
armed : TRUE if armed, FALSE otherwise.

Return value:
 None.

SeeAlso:
iHabitat.SetReactiveFunction, iHabitat.SetArmedWithTarget


iHabitat.SetArmedWithTarget

Arms a station, giving it an initial target.

prototype iHabitat.SetArmedWithTarget( hhabitat habitat, hisim target );

Parameters:
 habitat : The habitat to arm / disarm.
target : The target to fire at.

Return value:
None.

SeeAlso:
iHabitat.SetReactiveFunction, iHabitat.SetArmed


iHabitat.SetReactiveFunction

Set the function for stations to use when reacting to attack.

prototype iHabitat.SetReactiveFunction( string function );

Parameters:
function : The function to use.

Return value:
None.

SeeAlso:
iHabitat.SetArmed, iHabitat.SetArmedWithTarget


iLagrangePoint

A package governing Lagrange points.

Type definitions:

  • hlagrangepoint

Functions:

  • AddDestination
  • Cast
  • Create
  • FilterOnLocalDestination
  • FilterOnInterstellarDestination
  • FindByName
  • Interstellar
  • InterstellarDestinations
  • LocalDestinations
  • Nearest
  • Random
  • SetUsable


iLagrangePoint.hlagrangepoint

A handle to a Lagrange point object.

hlagrangepoint : hmapentity;

See also:
iMapEntity, iMapEntity.hmapentity.


iLagrangePoint.AddDestination

Get the usability of a given lagrange point, for autopilot and AI route finding.

prototype iLagrangePoint.AddDestination( hlagrangepoint lagrangepoint,  hlagrangepoint destination );

Parameters:
lagrangepoint : The Lagrange point to query.
flag : True to set the Lagrange point usable, false otherwise.

Return value:
None


iLagrangePoint.Cast

Cast a handle up to a handle to a Lagrange point.

prototype hlagrangepoint iLagrangePoint.Cast( hobject handle );

Parameters:
handle : The handle to cast.

Return value:
A handle to a Lagrange point.

Notes:
If the object handle is invalid or the object is not a Lagrange point then a null handle is returned.


iLagrangePoint.Create

Create a new Lagrange point sim.

prototype iLagrangePoint.Create();

Parameters:
None

Return value:
None

Notes:
The new Lagrange Point will have no destinations. To add destinations use the iLagrangePoint.AddDestination command.

The new Lagrange Point is not automatically placed into the world. You can place it wherever you wish using the Sim place commands.

See Also:
iLagrangePoint.AddDestination


iLagrangePoint.FilterOnLocalDestination

Filter a given set of Lagrange points based on a local Lagrange point.

prototype set iLagrangePoint.FilterOnLocalDestination( set points,
                                                       int dest );

Parameters:
points : A set of Lagrange points to filter.
dest : The number of a local Lagrange point.

Return value:
A set containing those members of the given set which have the given Lagrange point as one of their local destinations.

See also:
iMapEntity.SystemLagrangePoints, iLagrangePoint.FilterOnInterstellarDestination.


iLagrangePoint.FilterOnInterstellarDestination

Filter a given set of Lagrange points based on a destination system.

prototype set iLagrangePoint.FilterOnInterstellarDestination( set points,
                                                              string dest );

Parameters:
points : A set of Lagrange points to filter.
dest : The name of a solar system.

Return value:
A set containing those members of the given set which have the given system as one of their interstellar destinations.

See also:
iMapEntity.SystemLagrangePoints, iLagrangePoint.FilterOnLocalDestination.


iLagrangePoint.FindByName

Finds a Lagrange point matching a given name.

prototype hlagrangepoint iLagrangePoint.FindByName( string name );

Parameters:
name : The name to search for.

Return value:
A handle to a Lagrange point matching the given name, or a null handle if the search failed.

Notes:
This function will only return the first Lagrange point with the given name.


iLagrangePoint.Nearest

Of a set of Lagrange points, find the closest to a given sim.

prototype hlagrangepoint iLagrangePoint.Nearest( set points,
                                                 hsim sim );

Parameters:
points : A set of handles to points.
sim : The sim to find the closest body to.

Return value:
The nearest Lagrange point to the given sim.

See also:
iMapEntity.SystemLagrangePoints, iLagrangePoint.FilterOnLocalDestination, iLagrangePoint.FilterOnInterstellarDestination, iLagrangePoint.Random.


iLagrangePoint.Interstellar

Return whether or not the Lagrange point is interstellar, i.e. allows ships to jump to/from another system.

prototype bool iLagrangePoint.Interstellar( hlagrangepoint lagrangepoint );

Parameters:
lagrangepoint : The Lagrange point to query.

Return value:
TRUE if the lagrange point is interstellar, FALSE othewise.


iLagrangePoint.LocalDestinations

Returns the set of local (in-system) destinations from this lagrange point.

prototype set iLagrangePoint.LocalDestinations( hlagrangepoint lagrangepoint );

Parameters:
lagrangepoint : The lagrange point to find the local destinations for.

Return value:
A set containing the handles of all the local destinations for the given lagrange point.

See Also:
iLagrangePoint.InterstellarDestinations


iLagrangePoint.InterstellarDestinations

Returns the set of interstellar destinations from this lagrange point.

prototype set iLagrangePoint.InterstellarDestinations( hlagrangepoint lagrangepoint );

Parameters:
lagrangepoint : The lagrange point to find the interstellar destinations for.

Return value:
A set containing the handles of all the interstellar destinations for the given lagrange point.

See Also:
iLagrangePoint.LocalDestinations


iLagrangePoint.Random

Pick a random Lagrangepoint from a given set.

prototype hlagrangepoint iLagrangePoint.Random( set points );

Parameters:
points : A set of handles to points.

Return value:
A random selection from the given set.

See also:
iMapEntity.SystemLagrangePoints, iLagrangePoint.FilterOnLocalDestination, iLagrangePoint.FilterOnInterstellarDestination, iLagrangePoint.Nearest.


iLagrangePoint.SetUsable

Get the usability of a given lagrange point, for autopilot and AI route finding.

prototype iLagrangePoint.SetUsable( hlagrangepoint lagrangepoint, bool flag );

Parameters:
lagrangepoint : The Lagrange point to query.
flag : TRUE to set the Lagrange point usable, FALSE otherwise.

Return value:
None


iMapEntity

The iMapEntity package is used to query the geography of a solar system. The functions in it either query the solar system as a whole or query entities regardless of what kind of geographical entity they are.

Type definitions:

  • hmapentity

Functions:

General

  • Cast
  • CastIntToAllegiance
  • Children
  • EntityToEntityDistance
  • EntityToSimDistance
  • GeogIndex
  • Name
  • Parent
  • RadiusOfInfluence
  • ShipsInRadius
  • SimForEntity
  • SystemName
  • WaypointForEntity

Finding Map Entities

  • FindByName
  • FindByNameInSystem
  • SystemBodies
  • SystemBodiesInSystem
  • SystemCentre
  • SystemCentreForSystem
  • SystemEntities
  • SystemEntitiesForSystem
  • SystemHabitats
  • SystemHabitatsInSystem
  • SystemLagrangePoints
  • SystemLagrangePointsInSystem

Entity Status

  • IsDestroyed
  • IsHidden
  • IsVisibleOnMap
  • SetDestroyed
  • SetHidden
  • SetMapVisibility

Notes:

The iMapEntity package deals with system geographical entities: celestial bodies, man-made stations and settlements and Lagrange points. However, the functions in this package only deal with these objects generically. For functions dealing with specifics of different geographical entities use the package dealing with that entity type. For celestial bodies use iBody, for man-made habitats use iHabitat and for Lagrange points use iLagrangePoint.


iMapEntity.hmapentity

Handles dealing with geographical entities such as celestial bodies, man-made habitats and Lagrange points.

hmapentity : hobject;

Properties:
Name | Type | Read | Write | Description
radius_of_influence | float | • |  | The radius of influence around the entity.

See also:
iBody.hbody, iBody.hhabitat, iLagrangePoint.hlagrangepoint.


iMapEntity.Cast

Attempt to cast the given handle up to a map entity handle.

prototype hmapentity iMapEntity.Cast( hobject entity );

Parameters:
entity : The entity to cast.

Return value:
A handle to a map entity object, or a null handle if the given handle was invalid or not a handle to a valid map entity object.

Notes:
It is perfectly safe to use this function to determine whether or not a handle is a map entity object.


iMapEntity.CastIntToAllegiance

Cast an integer up to a member of the IeAllegiance enumeration.

prototype IeAllegiance iMapEntity.CastIntToAllegiance( int value );

Parameters:
value : The integer to cast up to an allegiance.

Return value:
A member of the IeAllegiance enumerator.

Notes:
The IeAllegiance enumerator is defined in MapEnumerations.h.


iMapEntity.Children

Get a set of the children of the given map entity,

prototype hmapentity iMapEntity.Children( hmapentity entity );

Parameters:
entity : The map entity to find the children of.

Return value:
A set of all the children of the map entity.

See also:
iMapEntity.Parent


iMapEntity.EntityToEntityDistance

Calculate the distance between two map entities.

prototype float iMapEntity.EntityToEntityDistance( hmapentity e1,
                                                   hmapentity e2 );

Parameters:
e1 : The first entity to calculate the distance between.
e2 : The second entity to caluculate the distance between.

Return value:
The distance between the two entities.

Notes:
If an entity has a physical representation (like a planet) then the radius is taken into account. If the entity has no physical representation then the position of the waypoint sim is used to calculate the distance. If the two entities overlap then the distance is returned as zero - thus a return value of zero means that the entities are touching or overlapping.

See also:
iMapEntity.EntityToSimDistance, Sim.DistanceBetween, Sim.DistanceBetweenCentres.


iMapEntity.EntityToSimDistance

Calculate the distance between a map entity and a sim.

prototype float iMapEntity.EntityToSimDistance( hmapentity entity,
                                                hsim sim );

Parameters:
entity : The entity to calculate the distance between.
sim : The sim to caluculate the distance between.

Return value:
The distance between the entity and the sim.

Notes:
If the entity has a physical representation (like a planet) then the radius is taken into account. If the entity has no physical representation then the position of the waypoint sim is used to calculate the distance. If the entity and the sim overlap then the distance is returned as zero - thus a return value of zero means that the entity and the sim are touching or overlapping.

See also:
iMapEntity.EntityToEntityDistance, Sim.DistanceBetween, Sim.DistanceBetweenCentres.


iMapEntity.GeogIndex

Return the geography index of a given map entity

prototype int iMapEntity.IsDestroyed( hmapentity entity );

Parameters:
entity : The entity to check.

Return value:
The geography index.


iMapEntity.Name

Returns the name of a given map entity.

prototype string iMapEntity.Name( hmapentity entity );

Parameters:
entity : The map entity to get the name of.

Return value:
The name of the given map entity.


iMapEntity.Parent

Get the parent entity for this entity

prototype hmapentity iMapEntity.Parent( hmapentity entity );

Parameters:
entity : The map entity to find the parent of.

Return value:
A handle to the parent, or a null handle if none.

See Also:
iMapEntity.Children


iMapEntity.RadiusOfInfluence

Find the radius of influence of a map entity.

prototype float iMapEntity.RadiusOfInfluence( hmapentity entity );

Parameters:
entity : The map entity to find the radius of influence from.

Return value:
The radius of influence in metres.

Notes:
Lagrange points do not have a radius of influence.


iMapEntity.ShipsInRadius

Generate a set of all ships within a given radius of a given map entity.

prototype set iMapEntity.ShipsInRadius( hmapentity entity,
                                        float radius );

Parameters:
entity : The entity to query.
radius : The radius around the entity to search.

Return value:
A set of all ships within the given radius of the given entity.


iMapEntity.SimForEntity

Get the physical representation sim of a given map entity.

prototype hsim iMapEntity.SimForEntity( hmapentity entity );

Parameters:
hmapentity : The map entity to retrieve the physical representation for.

Return value:
The physical representation sim for a given entity, or a null handle if there is no such sim for the given entity.

Notes:
Not all map entities have physical representations so ensure that the handle returned from this function is checked.

See also:
iMapEntity.WaypointForEntity.


iMapEntity.SystemName

Get the name of the current solar system.

prototype string iMapEntity.SystemName();

Return value:
Returns the name of the current solar system or an empty string if there is no current system.


iMapEntity.WaypointForEntity

Get the waypoint sim of a given map entity.

prototype hsim iMapEntity.WaypointForEntity( hmapentity entity );

Parameters:
hmapentity : The map entity to retrieve the waypoint for.

Return value:
The waypoint for a given entity, or a null handle if there is no waypoint for the given entity.

Notes:
Not all map entities have waypoints so ensure that the handle returned from this function is checked.

See also:
iMapEntity.SimForEntity.


iMapEntity.FindByName

Try to find a specific map entity object from its name.

prototype hmapentity iMapEntity.FindByName( string name );

Parameters:
name : The name to search on.

Return value:
A handle to the desired map entity, or a null handle.

Notes:
If there are two or more map entities with the given name then only the first is returned.


iMapEntity.FindByNameInSystem

Try to find a specific map entity object from its name, in a given system

prototype hmapentity iMapEntity.FindByNameInSystem( string name, string system );

Parameters:
name : The name to search on.
system : The system to search in.

Return value:
A set of the desired sims.

Notes:
If there are two or more sims with the given name then only the first is returned.


iMapEntity.SystemBodies

Get a set of all celestial bodies in the system.

prototype set iMapEntity.SystemBodies();

Return value:
A set consisting of handles to all the celestial bodies in the current solar system.

See also:
iMapEntity.SystemBodiesInSystem, iMapEntity.SystemHabitats, iMapEntity.SystemLagrangePoints.


iMapEntity.SystemBodiesInSystem

Get a set of all celestial bodies in the specified system.

prototype set iMapEntity.SystemBodies( string system );

Parameters:
system : The system to find the bodies for.

Return value:
A set consisting of handles to all the celestial bodies in the specified solar system.

See also:
iMapEntity.SystemBodies, iMapEntity.SystemHabitatsInSystem, iMapEntity.SystemLagrangePointsInSystem.


iMapEntity.SystemCentre

Returns the system centre of the current system - the root entity that all other entities in the system are children of.

prototype hmapentity iMapEntity.SystemCentre();

Return value:
A handle to the root map entity of the specified system, if one exists.

Notes:
The handle returns is a handle to a map entity. If this entity is to be treated as a celestial body then iBody.Cast should be used.

See also:
iMapEntity.SystemCentreForSystem, iBody.Cast


iMapEntity.SystemCentreForSystem

Returns the system centre of the specified system - the root entity that all other entities in the system are children of.

prototype hmapentity iMapEntity.SystemCentreForSystem( string system );

Parameters:
system : The system to find the centre for.

Return value:
A handle to the root map entity of the specified system, if one exists.

Notes:
The handle returns is a handle to a map entity. If this entity is to be treated as a celestial body then iBody.Cast should be used.

See also:
iMapEntity.SystemCentre, iBody.Cast.


iMapEntity.SystemEntities

Get a set of all of the entities in the solar system.

prototype set iMapEntity.SystemEntities();

Parameters:
None.

Return value:
A set of handles to all the entities in the solar system.

See also:
iMapEntity.SystemEntitiesForSystem, iMapEntity.SystemBodies, iMapEntity.SystemHabitats, iMapEntity.SystemLagrangePoints.


iMapEntity.SystemEntitiesForSystem

Get a set of all of the entities in the specified solar system.

prototype set iMapEntity.SystemEntities( string system );

Parameters:
system : The system to find the entities for.

Return value:
A set of handles to all the entities in the specified solar system.

See also:
iMapEntity.SystemEntities, iMapEntity.SystemBodiesInSystem, iMapEntity.SystemHabitatsInSystem, iMapEntity.SystemLagrangePointsInSystem.


iMapEntity.SystemHabitats

Get a set of all habitats in the system.

prototype set iMapEntity.SystemHabitats();

Return value:
A set consisting of handles to all the habitats in the current solar system.

See also:
iMapEntity.SystemHabitatsInSystem, iMapEntity.SystemBodies, iMapEntity.SystemLagrangePoints.


iMapEntity.SystemHabitatsInSystem

Get a set of all habitats in the specified system.

prototype set iMapEntity.SystemHabitatsInSystem( string system );

Parameters:
system : The system to find the habitats in.

Return value:
A set consisting of handles to all the habitats in the specified solar system.

See also:
iMapEntity.SystemHabitats, iMapEntity.SystemBodiesInSystem, iMapEntity.SystemLagrangePointsInSystem.


iMapEntity.SystemLagrangePoints

Get a set of all Lagrange points in the system.

prototype set iMapEntity.SystemLagrangePoints();

Return value:
A set consisting of handles to all the Lagrange points in the current solar system.

See also:
iMapEntity.SystemLagrangePointsInSystem, iMapEntity.SystemHabitats, iMapEntity.SystemBodies.


iMapEntity.SystemLagrangePointsInSystem

Get a set of all Lagrange points in the specified system.

prototype set iMapEntity.SystemLagrangePointsInSystem( string system );

Parameters:
system : The system to find the bodies for.

Return value:
A set consisting of handles to all the Lagrange points in the specified solar system.

See also:
iMapEntity.SystemLagrangePoints, iMapEntity.SystemHabitatsInSystem, iMapEntity.SystemBodiesInSystem.


iMapEntity.IsDestroyed

Check if a given map entity has been destroyed.

prototype bool iMapEntity.IsDestroyed( hmapentity entity );

Parameters:
entity : The entity to check.

Return value:
TRUE if the entity is destroyed, FALSE otherwise.

See Also:
iMapEntity.SetDestroyed


iMapEntity.IsHidden

Check the visibility of the map entity.

prototype bool iMapEntity.IsHidden( hmapentity entity );

Parameters:
entity : The entity to check.

Return value:
TRUE if the entity is hidden, FALSE otherwise.

See Also:
iMapEntity.SetHidden


iMapEntity.IsVisibleOnMap

Check the map visibility of the map entity.

prototype bool iMapEntity.IsVisibleOnMap( hmapentity entity );

Parameters:
entity : The entity to check

Return value:
TRUE if the entity is visible on the map, FALSE otherwise.

See Also:
iMapEntity.SetMapVisibility


iMapEntity.SetDestroyed

Change the destroyed status of a given map entity.

prototype iMapEntity.SetDestroyed( hmapentity entity, bool destroyed );

Parameters:
entity : The entity to destroy / resurrect.
destroyed : TRUE to destroy, FALSE otherwise.

Return value:
None.

Notes:
This function is useful to resurrect a map entity that's previously been destroyed by the player or game script.
Destroying a map entity also hides it and removes it from the map, in addition to setting its destroyed status.
When a map entity is resurrected any checks to see if it's been destroyed will return false, as though it had never been destroyed.

See Also:
iMapEntity.IsDestroyed


iMapEntity.SetHidden

Hide the given map entity, removing it from the world.

prototype iMapEntity.SetHidden( hmapentity entity, bool hide );

Parameters:
entity : The entity to hide / unhide.
hide : TRUE to hide, FALSE otherwise.

Return value:
None.

Notes:
Hiding a map entity does not hide it on the map. Use iMapEntity.SetMapVisibility to do this.

See Also:
iMapEntity.IsHidden


iMapEntity.SetMapVisibility

Set the map visibility of the given entity.

prototype iMapEntity.SetMapVisibility( hmapentity entity, bool visible );

Parameters:
entity : The entity to set the map visibility for.
visible : TRUE for visible on the map, FALSE otherwise.

Return value:
None.

Notes:
The map visibility setting will be saved out in the saved game.
The entity is invisible on the map, but will be visible in the game. If a map entity is found by the player while non-map visible, then it is automatically made visible on the map.

See Also:
iMapEntity.IsVisibleOnMap


iRemotePilot

The iRemotePilot package is used to enable and disable the remote piloting of ships.

Functions:

  • DeactivateConnection
  • EnableRemoteConnection
  • Install
  • RemoteActive
  • ReturnCurrentRemoteVessel

Notes:

Only ships (hship) can be remote piloted.


iRemotePilot.EnableRemoteConnection

Enables / disables the ability to remote link to a ship.

prototype iRemotePilot.EnableRemoteConnection( hship ship, bool flag );

Parameters:
ship : The ship to enable / disable the connection for.
flag : TRUE to enable, FALSE to disable.

Notes:
This command doesn't actually make the player remote pilot a ship; it turns on or off the ability to remote pilot a vessel.

See also:
iRemotePilot.DeactivateConnection


iRemotePilot.DeactivateConnection

Force the disconnection of any remote pilot connection.

prototype iRemotePilot.DeactivateConnection();

Parameters:
None.

Return value:
None.


iRemotePilot.Install

Activates the keybinding for the remote pilot function.

prototype iRemotePilot.Install();

Parameters:
None.

Return value:
None.


iRemotePilot.RemoteActive

Check if the player is currently remote piloting a ship.

prototype bool iRemotePilot.RemoteActive();

Parameters:
None.

Return value:
TRUE if the remote link is active, FALSE otherwise.

See Also:
 iRemotePilot.ReturnCurrentRemoteVessel


iRemotePilot.ReturnCurrentRemoteVessel

Return the current remote vessel.

prototype hship iRemotePilot.ReturnCurrentRemoteVessel();

Parameters:
None.

Return value:
The handle of the current remote vessel, or none if no vessel is being remote piloted.

See Also:
 iRemotePilot.RemoteActive


iRegion

The iRegion package is used to create and manipulate LDSi ( LDS drive inhibiting ) and Traffic Control regions.

Type definitions:

  • hregion

Functions:

  • CreateLDSI
  • CreateTrafficControl
  • Destroy
  • NthSim
  • SimCount

Notes:

Traffic control regions are used around stations to limit the speed of sims around the stations. LDSi regions are used around Lagrange Points to prevent ships using LDS immediately upon exiting an L-Point.


iRegion.hregion

Handles dealing with LDSi and Traffic Control regions.

hregion : hobject;


iRegion.Destroy

Destroys the specified region.

prototype iRegion.Destroy( hregion region );

Parameters:
region : The region to destroy.

Return value:
None.

See also:
iRegion.CreateLDSI, iRegion.CreateTrafficControl


iRegion.CreateLDSI

Creates an LDSi region centred on the given sim.

prototype hregion iRegion.CreateLDSI( hsim sim, float radius );

Parameters:
sim : The sim to place the field around.
radius : The radius of the field in metres.

Return value:
The handle to the region.

Notes:
The LDSI region will disable the LDS drive of any ship in its radius.

See also:
iRegion.CreateTrafficControl, iRegion.Destroy


iRegion.CreateTrafficControl

Creates a Traffic Control region centred on the given sim

prototype hregion iRegion.CreateLDSI( hsim sim, float radius, float speed_limit );

Parameters:
sim : The sim to place the region around.
radius : The radius of the region in metres.
speed_limit : The speed limit of the region, in metres per second.

Return value:
The handle to the region.

Notes:
The Traffic Control region will disable the LDS drive of any ship in its radius, as well as limiting the sim's speed to the speed limit.

To enable a sim to ignore the speed limit add the boolean property "ignore_speed_limit" to the sim, giving it the value TRUE. e.g.

    Object.SetBoolProperty( ship, "ignore_speed_limit", true );

See also:
iRegion.CreateLDSI, iRegion.Destroy


iRegion.NthSim

Return the Nth sim in the specified region.

prototype hsim iRegion.NthSim( hregion region, int nth );

Parameters:
region : The region to check.
nth : The Nth sim to return.

Return value:
The handle of the region's Nth sim.

See also:
iRegion.SimCount


iRegion.SimCount

Returns the number of sims in the specified region.

prototype int iRegion.SimCount( hregion region );

Parameters:
region : The region to check.

Return value:
The number of sims in the region.

See also:
iRegion.NthSim


iShip

I-War II Ship package. Enables the creation and manipulation of ships through Pog.

Type definitions:

  • hship

Functions:

General

  • Cast
  • FindPlayerShip
  • IsTrueShip
  • RandomName
  • Heal
  • RecalculateMOIFromMass
  • ResetPlayer

Creation

These functions deal with creating ships.

  • Create
  • CreatePlayerShip
  • CreateTurretFighters

Pilots

These functions deal with installing and manipulating ship pilots.

  • InstallAIPilot
  • InstallPlayerPilot
  • PilotSkillLevel
  • RemovePilot
  • SetPilotSkillLevel

Docking

These functions deal with docking and undocking ships.

  • Dock
  • Undock
  • UndockSelf

Combat and Sensors

These functions deal with combat and target detection.

  • Attacked
  • BrightnessOf
  • CurrentTarget
  • HasFired
  • HasHyperspaceTracker
  • HyperspaceTrackerContact
  • HyperspaceTrackerTarget
  • LastAttacker
  • LastFireTarget
  • LockDownWeapons
  • MaxSensorRange
  • PercentageThrusterEmission
  • WeaponTargetsFromContactList
  • WeaponsUseExplicitTarget

Ship Movement and Drives

These functions deal with ship movement and drives.

  • CancelDisrupt
  • Disrupt
  • DisruptLDSDrive
  • IsAIDisabled
  • IsDisrupted
  • IsFreeWithoutPilot
  • IsInLDS
  • IsLDSInhibited
  • IsLDSScrambled
  • SetAIDisabled
  • SetFreeWithoutPilot


iShip.hship

Handle to a space ship object.

hship : hisim;

Properties:
Name | Type | Read | Write | Description
max_linear_speed | vector | • | • | The maximum linear speed of the ship
max_linear_thrust | vector | • | • | The maximum linear thrust of the ship
max_angular_speed | vector | • | • | The maximum angular speed of the ship
max_angular_thrust | float | • | • | The maximum angular thrust of the ship
angular_speed_boost | float | • | • | The angular speed boost of the ship
threat | float | • | • | The base threat level of the ship


iShip.Cast

Casts a handle to a ship handle.

prototype hship iShip.Cast( hobject handle );

Parameters:
handle : A handle to an object that is a ship.

Return value:
Returns the ship handle.

Notes:
The cast function is especially useful when using collections like sets and lists, which return handles which need to be cast before they can be used as a specific type.


iShip.FindPlayerShip

Find the handle of the ship to which the player pilot is installed.

prototype hship iShip.FindPlayerShip( );

Return value:
Returns the ship handle of the player ship.

Notes:
If the player pilot is not installed in any ship the the handle will be equal to none.


iShip.IsTrueShip

Returns true if the given ship is a true ship (and therefore player compatable) rather than simply a piloted sim.

prototype bool iShip.IsTrueShip( hship ship );

Parameters:
ship : A handle to a ship.

Return value:
TRUE if the ship is a true ship, FALSE otherwise.

See also:
iShip.InstallPlayerPilot, iShip.Cast


iShip.RandomName

Creates a random name for the ship specified.

prototype string iShip.RandomName( hsim ship );

Parameters:
ship : The handle of a ship for which to generate a name.

Return value:
Returns a string containing the random name generated for the ship.


iShip.Heal

Heal a ship and its systems up to full health.

prototype bool iShip.Heal( hship ship );

Parameters:
ship : A handle to a ship.

See Also:
iShip.ResetPlayer


iShip.RecalculateMOIFromMass

Recalculate Moment of Inertia and torque from new mass.

prototype iShip.RecalculateMOIFromMass( hship ship );

Parameters:
ship : A handle to a ship.

Return value:
None

Notes:
This command is used after a Sim.SetMass command to ensure that the ship's movement matches its new mass.

See Also:
Sim.SetMass


iShip.ResetPlayer

Reset the player ship state - reseting TRI settings, turning off LDS etc.

prototype iShip.ResetPlayer();

Parameters:
None.

Return value:
None.

See Also:
iShip.Heal


iShip.Create

Creates a ship using the specified ship template.

prototype hship iShip.Create( string template, string name );

Parameters:
template : The resource URL for the ship template file.
name : The name to give the ship.

Return value:
Returns a handle to a new ship object.

Notes:
The template name is a Flux resource URL and should point to a suitable ship template INI file.

See also:
Sim.Create.


iShip.CreatePlayerShip

Create the player ship - uses whichever ship is currently setup in the player loadout.

prototype hship iShip.CreatePlayerShip( string name );

Parameters:
name : The name to give the ship.

Return value:
Returns a handle to a new ship object.

See also:
iShip.Create, Sim.Create, iShip.CreateTurretFighters


iShip.CreateTurretFighters

Create the turret fighters - uses the turret fighter setup in the player loadout.

prototype list iShip.CreateTurretFighters();

Parameters:
None

Return value:
A list of turret fighter handles.

See also:
iShip.Create, Sim.Create, iShip.CreatePlayerShip


iShip.InstallAIPilot

Install an AI pilot in this ship.

prototype iShip.InstallAIPilot( hship ship, float ignore_fight,
                float fight_flee, float self_preserve_ratio,
                string ignore_function, string fight_function,
                string flee_function, string self_preserve_function );

Parameters:
ship : A handle to a ship.
fight_flee : The fight or flee (uppermost) threat ratio.
ignore_fight : The ignore or fight (lowermost) threat ratio.
self_preserve_ratio : Self preservation hitpoint/max hitpoint ratio.
fight_function : Alternative script function to call if fight is signalled.
flee_function : Alternative script function to call if flee is signalled.
ignore_function : Alternative script function to call if ignore is signalled.
self_preserve_function : Alterantive script function to call if self preservation is signalled.

Notes:
If the ship has a player pilot then the player pilot is removed from the ship and is not attached to any ship. If the ship already has an AI pilot then there is no change. If either of the alternative script functions are not desired use "". The ratios described above are relative to the threat of the ship.

See also:
iShip.InstallPlayerPilot, iShip.RemovePilot.


iShip.InstallPlayerPilot

Install a player pilot in this ship.

prototype iShip.InstallPlayerPilot( hship ship );

Parameters:
ship : A handle to a ship.

Notes:
There can only be one player pilot present in the world. This means that installing a player pilot in a ship will remove the player pilot from any ship that it might currently be installed within. This leaves the ship pilotless.

See also:
iShip.InstallAIPilot, iShip.RemovePilot.


iShip.PilotSkillLevel

Gets the pilot skill level of an AI piloted ship.

prototype float iShip.PilotSkillLevel( hship ship );

Parameters:
ship : A handle to a ship.

Return value:
The skill level of the pilot ranged between 0 an 1, where 0 is minimum skill, and 1 maximum skill.

See also:
iShip.SetPilotSkillLevel, iShip.InstallAIPilot


iShip.RemovePilot

Removes any pilot from the specified ship.

prototype iShip.RemovePilot( hship ship );

Parameters:
ship : A handle to a ship.

Notes:

See also:
iShip.InstallAIPilot, iShip.InstallPlayerPilot


iShip.SetPilotSkillLevel

Sets the skill level of an AI pilot.

prototype iShip.SetPilotSkillLevel( float skill );

Parameters:
skill : A skill value ranged between 0 an 1, where 0 is minimum skill, and 1 maximum skill.

Return value:
None

See also:
iShip.PilotSkillLevel, iShip.InstallAIPilot


iShip.Dock

Instantly dock the given ship to the given sim.

prototype bool iShip.Dock( hship ship, hsim sim );

Parameters:
ship : A handle to a ship.
sim : A handle to a sim.

Return value:
TRUE if the docking was successful, FALSE otherwise.

Notes:
The ship and its target sim must have compatible and free dockports, otherwise docking will be unsuccessful.
If the ship has the higher docking priority, the sim will move to the ship, otherwise the ship will move to the sim.

See Also:
iShip.Undock, iShip.UndockSelf


iShip.UnDock

Undock the given ship from from the given sim.

prototype bool iShip.Undock( hship ship, hisim sim );

Parameters:
ship : A handle to a ship.
sim : A handle to a sim.

Return value:
TRUE if the undocking was successful, FALSE otherwise.

Notes:
If the docking lock is set, it must be released for this to work.

See Also:
iShip.UndockSelf, iShip.Dock


iShip.UnDockSelf

Undock the given ship from whatever it's docked to.

prototype bool iShip.UndockSelf( hship ship );

Parameters:
ship : A handle to a ship.

Return value:
TRUE if the undocking was successful, FALSE otherwise.

Notes:
If the docking lock is set, it must be released for this to work.

See Also:
iShip.Undock, iShip.Dock


iShip.Attacked

Check if the given ship has been attacked.

prototype iShip.Attacked( hship ship );

Parameters:
ship : A handle to a ship.

Return value:
TRUE if the ship has been attacked, FALSE otherwise.

Notes:
Using this function resets the 'attacked' flag on the ship.

It's a good idea to use this function once just before you start checking if the ship has been attacked. This ensures the attacked flag is cleared before you start checking if it's been attacked. Otherwise if the attacked flag has already been set before you started checking the ship, your script would assume it had been attacked immediately.

See also:
iShip.LastAttacker


iShip.BrightnessOf

Returns the brightness of a given vessel from the viewpoint of the sim with the given distance attenuation factor -- used to represent sensor ability. Attenuation is either linear or squared ('square_attenuation') over this distance.

prototype float iShip.BrightnessOf( hship ship,
                    hsim sim,
                    float attenuation_range,
                    bool squared_attenuation );

Parameters:
ship : A handle to a ship.
sim : The sim to view the ship's brightness from.
attenuation_range : The range over which the brightness attenuates.
squared : TRUE for squared attenuation, FALSE for linear.

Return value:
The brightness value.

Notes:
This function is used to check how visible a ship is to another, and is useful for times when the player must move slowly and stealthily to avoid detection.

See also:
iShip.PercentageThrusterEmission


iShip.CurrentTarget

Returns the current target of the given ship.

prototype hisim iShip.CurrentTarget( hship ship );

Parameters:
ship : A handle to a ship.

Return value:
Returns the handle of the ship's target sim.

Notes:
This is the contact picked from the contact list by the current pilot this is NOT the explicit target.


iShip.HasFired

Check if the given ship has fired.

prototype iShip.HasFired( hship ship );

Parameters:
ship : A handle to a ship.

Return value:
TRUE if the ship has fired, FALSE otherwise.

Notes:
Using this function resets the 'has fired' flag on the ship.

It's a good idea to use this function once just before you start checking if the ship has fired. This ensures the 'has fired' flag is cleared before you start checking if it has fired.. Otherwise if the 'has fired' flag has already been set before you started checking the ship, your script would assume it has fired immediately.

See also:
iShip.LastFireTarget


iShip.HasHyperspaceTracker

Check to see if the given player ship has the hyperspace tracker.

prototype bool iShip.HasHyperspaceTracker( hship ship );

Parameters:
ship : A handle to a player ship.

Return value:
TRUE if the ship has the hyperspace tracker, FALSE otherwise.

See also:
iShip.HyperspaceTrackerContact, iShip.HyperspaceTrackerTarget


iShip.HyperspaceTrackerContact

Returns the last contact tracked through hyperspace.

prototype hisim iShip.HyperspaceTrackerContact();

Parameters:
None.

Return value:
The handle to the last tracked contact.

See also:
iShip.HasHyperspaceTracker, iShip.HyperspaceTrackerTarget


iShip.HyperspaceTrackerTarget

Returns the target of the last contact tracked through hyperspace.

prototype hisim iShip.HyperspaceTrackerTarget();

Parameters:
None.

Return value:
The handle to the target of the last tracked contact.

See also:
iShip.HasHyperspaceTracker, iShip.HyperspaceTrackerContact


iShip.LastAttacker

Returns the last attacker of a ship.

prototype hisim iShip.LastAttacker( hship ship );

Parameters:
ship : A handle to a ship.

Return value:
Returns the handle of the ship's last attacker.

Notes:
This function doesn't clear the ship's 'attacked' flag.

See also:
iShip.Attacked


iShip.LastFireTarget

Returns the last fire target of a ship.

prototype hobobject iShip.LastFireTarget( hship ship );

Parameters:
ship : A handle to a ship.

Return value:
Returns the handle of the ship's last fire target. This may be a subsim.

Notes:
This function doesn't clear the ship's 'has fired' flag.

See also:
iShip.HasFired


iShip.LockDownWeapons

Locks all weapons down on the ship, preventing them from firing, including any turrets.

prototype bool iShip.LockDownWeapons( hship ship );

Parameters:
ship : A handle to a ship.

Return value:
TRUE if the locking down was successful, FALSE otherwise.

Notes:
This command doesn't affect the ship's movement, so it's possible to stop a ship firing while it's attacking a target, without affecting the way the ship maneuvers.

See Also:
iShip.WeaponTargetsFromContactList, iShip.WeaponsUseExplicitTarget


iShip.MaxSensorRange

Find and return the maximum (i.e. undamaged) sensor range of a given ship.

prototype float iShip.MaxSensorRange( hship ship )

Parameters:
ship : A handle to a ship.

Return value:
The maximum sensor range in metres.


iShip.PercentageThrusterEmission

Returns the percentage thruster emission (the percentage emission of a ship's thrusters from max.)

prototype float iShip.PercentageThrusterEmission( hship ship );

Parameters:
ship : A handle to a ship.

Return value:
The percentage thruster emission.

Notes:
This function is used to check how heavy a ship is using its thrusters, and is useful for times when the player must move slowly and stealthily to avoid detection.

See also:
iShip.BrightnessOf


iShip.WeaponTargetsFromContactList

Sets all weapon targets from the contact list (generic attack weapon mode).

bool iShip.WeaponTargetFromContactList( hship ship )

Parameters:
ship : A handle to a ship.

Return value:
TRUE if the function was successful, FALSE otherwise.

Notes:
In this mode a ship's weapons will automatically fire on any hostile target on their contact list that are in their weapon fire arcs.

This command allows the weapons to act independently of the ship's movement, for example a ship could approach a friendly station while automatically firing at any hostiles nearby.

See Also:
iShip.WeaponsUseExplicitTarget, iShip.LockDownWeapons


iShip.WeaponsUseExplicitTarget

Sets all weapons on a ship to attack the given target.

bool iShip.WeaponsUseExplicitTarget( hship ship, hsim target );

Parameters:
ship : A handle to a ship.
target : The target to attack.

Return value:
TRUE if the function was successful, FALSE otherwise.

Notes:
In this mode a ship's weapons will fire on the given target if it is in any weapon fire arc.

This command allows the weapons to act independently of the ship's movement, for example a ship could approach a friendly station while automatically firing at a hostile cruiser nearby.

See Also:
iShip.WeaponTargetsFromContactList, iShip.LockDownWeapons


iShip.CancelDisrupt

Cancel the disruption of a given ship.

prototype iShip.CancelDisrupt( hship ship );

Parameters:
ship : The ship to cancel the disrupt for.

Return value:
None

See also:
iShip.Disrupt, iShip.IsDisrupted


iShip.Disrupt

Disrupts the given ship for the given time. If shields_only is TRUE, only the shields will be disrupted.

prototype iShip.Disrupt( hship ship, float time, bool shields_only );

Parameters:
ship : The ship to disrupt
time : The time in seconds to disrupt for.
shields_only : TRUE to disrupt shields only, FALSE to fully disrupt.

Return value:
None

See also:
iShip.CancelDisrupt, iShip.IsDisrupted


iShip.DisruptLDSDrive

Ensures any LDS drive on a ship is disrupted for the given time.

prototype iShip.DisruptLDSDrive( hship ship, float time );

Parameters:
ship : The ship to disable the LDS drive on.
time : The time in seconds to disable the LDS drive.

Return value:
None

See also:
iShip.IsInLDS, iShip.IsLDSInhibited, iShip.IsLDSScrambled


iShip.IsAIDisabled

Check to see if the given ship's AI is disabled.

prototype bool iShip.IsAIDisabled( hship ship );

Parameters:
ship : A handle to a ship.

Return value:
TRUE if the ship's AI is disabled, FALSE otherwise.

See also:
iShip.SetAIDisabled


iShip.IsDisrupted

Check to see if the given ship is disrupted.

prototype bool iShip.IsDisrupted( hship ship );

Parameters:
ship : A handle to a ship.

Return value:
TRUE if the ship is disrupted, FALSE otherwise.

See also:
iShip.Disrupt, iShip.CancelDisrupt


iShip.IsFreeWithoutPilot

Check to see if the given ship is set to drift mode, without pilot control.

prototype bool iShip.IsFreeWithoutPilot( hship ship );

Parameters:
ship : A handle to a ship.

Return value:
TRUE if the ship is free without pilot, FALSE otherwise.

See also:
iShip.SetFreeWithoutPilot


iShip.IsInLDS

Check to see if the given ship has an LDS drive and is in LDS.

prototype bool iShip.IsInLDS( hship ship );

Parameters:
ship : A handle to a ship.

Return value:
TRUE if the ship is a true ship, FALSE otherwise.

See also:
iShip.DisruptLDSDrive, iShip.IsLDSScrambled, iShip.DisruptLDSDrive


iShip.IsLDSInhibited

Check to see if the given ship is LDS inhibited.

prototype bool iShip.IsLDSInhibited( hship ship );

Parameters:
ship : A handle to a ship.

Return value:
TRUE if the ship is LDS inhibited, FALSE otherwise.

See also:
iShip.IsLDSScrambled, iShip.DisruptLDSDrive, iShip.IsInLDS


iShip.IsLDSScrambled

Check to see if the given ship is LDS scrambled ( i.e. hit by an LDSi Missile ).

prototype bool iShip.IsLDSScrambled( hship ship );

Parameters:
ship : A handle to a ship.

Return value:
TRUE if the ship is LDS scambled, FALSE otherwise.

See also:
iShip.IsLDSInhibited, iShip.DisruptLDSDrive, iShip.IsInLDS


iShip.SetAIDisabled

Turn on / off the AI for the given ship.

prototype iShip.SetAIDisabled( hship ship, bool disable );

Parameters:
ship : The ship to disrupt
disable : TRUE to disable the ship's AI, FALSE to enable.

Return value:
None.

See also:
iShip.ISAIDisabled


iShip.SetFreeWithoutPilot

Turn on / off drift mode for the given ship. ( Free flight mode without pilot ).

prototype iShip.SetFreeWithoutPilot( hship ship, bool free );

Parameters:
ship : The ship to disrupt
free : TRUE to enable drift mode, FALSE to disable.

Return value:
None.

Notes:
In drift mode a ship cannot maneuver, and will simply drift without pilot control. However weapons can still fire on any target that crosses their fire arc.

See also:
iShip.IsFreeWithoutPilot


iSim

The iSim package provides advanced sim manipulations commands specific to I-War 2, for use with the I-War 2 sim type (hisim). All of these commands can also be used with I-War 2 ship sim-types (hship), as hships are derived from hisims.

Type definitions:

  • hisim
  • eSimType
  • eExplosion

Functions:

General

  • Cast
  • CreateExplosion
  • Kill
  • StartExplosion
  • StopExplosion

Sim Attributes

These functions query or modify various sim attributes, such as indestructability.

  • Faction
  • IsDying
  • IsIndestructable
  • IsMissionCritical
  • IsRespawning
  • SetFaction
  • SetIndestructable
  • SetMissionCritical
  • Type

Finding Sims

These functions provide various ways of finding sims or sets of sims.

  • FindByNameInSystem
  • FindByWildCardInSystem
  • NonPlanetaryInRadius
  • PlayerHostilesInRadius
  • SimsInCone
  • SimsInCylinder
  • SimsInRadius
  • SimsInRadiusFromSet
  • SimsInRadiusOfFaction
  • ShipsInRadius

Docking

Thes functions deal with the docking and undocking of sims.

  • Dock
  • IsDocked
  • IsDockedTo
  • IsDockedToStructure
  • SetDockingLock
  • Undock

Jumping Between Systems

These functions are used to move sims between systems and to query the current active system.

  • ActiveWorld
  • CapsuleJump
  • CapsuleJumpCustom
  • CapsuleJumpStaggered
  • IsCapsuleJumping
  • WorldName

Combat and Sensors

These functions deal with sensor visibility and combat related functions.

  • Attacked
  • LastAttacker
  • LockDownWeapons
  • SetHostile
  • SetSensorVisibility
  • SetStandardSensorVisibility
  • WeaponTargetsFromContactList
  • WeaponsUseExplicitTarget

Alien Effects

These functions deal with the aliens and the damage they cause.

  • AlienInfectionDamage
  • AlienInfectionEffect
  • IsAlienInfectionEffectOn
  • SetAlienInfectionDamage


iSim.hisim

I-War II sim handle.

hisim : hsim;

Properties:
Name | Type | Read | Write | Description
brightness | float | • |  | The brightness of the sim
hit_points | float | • | • | The number of hit points of the sim
armour | float | • | • | The armour class of the sim
docking_priority | float | • | • | The docking priority of the sim

See also:
sim.hsim.


iSim.eExplosion

This enumeration is used for the different explosion types.

enum eExplosion
{
    SE_Normal,
    SE_AntiMatter
};

Notes:
The declaration of this enumeration can be found in iSim.h.


iSim.eSimType

This enumeration is used for the different sim types. These can be combined as a bitfield so that the types can be referenced safely by name.

enum eSimType
{
    // No type
    T_None				= 0x00000000,

    // Celestial bodies
    T_Star				= 0x00000001,
    T_Planet				= 0x00000002,
    T_Nebula				= 0x00000004,

    // Non-ships (not avoided)
    T_Waypoint			= 0x00000008,
    T_LagrangePoint			= 0x00000010,
    T_Probe				= 0x00000020,

    // Weapons
    T_Weapon				= 0x00000040,
    T_Missile				= 0x00000080,
    T_Mine				= 0x00000100,

    // Camera dolly (not avoided)
    T_Dolly 	          		= 0x00000200,

    // Non-ships
    T_Asteroid			= 0x00000400,
    T_CargoPod			= 0x00000800,

    // Bases
    T_Gunstar				= 0x00001000,
    T_Station				= 0x00002000,
    T_BioBomber			= 0x00004000,

    // Ships (in rough size order)
    T_Drone				= 0x00008000,
    T_Waldo				= 0x00010000,
    T_CommandSection			= 0x00020000,
    T_Utility				= 0x00040000,
    T_Passenger			= 0x00080000,
    T_Fighter				= 0x00100000,
    T_Tug				= 0x00200000,
    T_Patcom				= 0x00400000,
    T_Interceptor			= 0x00800000,
    T_Corvette			= 0x01000000,
    T_Freighter			= 0x02000000,
    T_Destroyer			= 0x04000000,
    T_Cruiser				= 0x08000000,
    T_Carrier				= 0x10000000,

    // Other things
    T_Alien             		= 0x20000000,

    // Multiplayer features
    T_PowerUp           		= 0x40000000,

    //
    // Masks (combinations)
    //

    // All celestial phenomena
    TM_CelestialBody			= T_Star |
                      T_Planet |
                      T_Nebula,

    // All ships
    TM_Ship				= T_Drone |
                      T_Waldo |
                      T_CommandSection |
                      T_Utility |
                      T_Passenger |
                      T_Fighter |
                      T_Tug |
                      T_Patcom |
                      T_Corvette |
                      T_Freighter |
                      T_Destroyer |
                      T_Cruiser |
                      T_Interceptor |
                      T_Carrier
};

Notes:
The declaration of this enumeration can be found in iSim.h.


iSim.Cast

Cast an hobject handle to an hisim handle.

prototype hisim iSim.Cast( hobject the_handle );

Parameters:
the_handle : The handle to cast to an hisim handle.

Return value:
Returns a hisim handle. Returns none if the handle would not be a valid hisim.

Notes:
This can be used to cast objects so that common functionality like factions can be accessed.

See also:
iSim.hisim.


iSim.CreateExplosion

Creates an explosion on the given sim.

prototype iSim.CreateExplosion( hisim sim );

Parameters:
sim : The sim to create the explosion on.

Return value:
None.

Notes:
The Sim is unharmed and not destroyed.

See also:
iSim.StartExplosion, iSim.StopExplosion


iSim.Kill

Destroy a sim, with explosions.

prototype iSim.Kill( hisim sim );

Parameters:
sim : The sim to kill

Return value:
None.

See also:
Sim.Destroy


iSim.StartExplosion

Starts the given sim exploding

prototype iSim.StartExplosion( hisim sim );

Parameters:
sim : The sim to explode

See also:
The given sim is unharmed while it is exploding. Use iSim.StopExplosion to stop the sim exploding.
This command is useful when you want an explosion to take a specific length of time, e.g. in a cutscene.

See also:
iSim.StopExplosion, iSim.CreateExplosion


iSim.StopExplosion

Stop a sim exploding and optionally destroy the sim with the given explosion type.

prototype iSim.StopExplosion( hisim sim,
                              eExplosion explosion,
                              bool destroy_sim );

Parameters:
sim : The sim to stop exploding.
explosion : The enum of the explosion type to use.
destroy_sim : TRUE to destroy the sim, FALSE otherwise.

See also:
This command can only be used to stop explosions started with iSim.StartExplosion.

See also:
iSim.StartExplosion, eExplosion , iSim.CreateExplosion


iSim.Faction

Get the faction handle from the object.

prototype hfaction iSim.Faction( hisim isim_handle );

Parameters:
isim_handle : handle to the isim.

Return value:
Returns the faction handle.

See also:
iSim.SetFaction, iFaction.


iSim.IsDying

Check if a given sim is exploding and dying, or has been killed.

prototype bool iSim.IsDying( hisim sim );

Parameters:
sim : The sim to check.

Return value:
Returns true if the sim is dying or dead.

See also:
Sim.IsDead


iSim.IsIndestructable

Returns true if the indestructible flag of the given sim has been set.

prototype bool iSim.IsIndestructable( hisim sim );

Parameters:
sim : The sim to check.

Return value:
Returns true if the indestructible flag has been set for this sim.

See also:
iSim.SetIndestructable.


iSim.IsMissionCritical

Returns true if the mission critical flag of the given sim has been set.

prototype bool iSim.IsMissionCritical( hisim sim );

Parameters:
sim : The sim to check.

Return value:
Returns TRUE if the mission critical flag has been set for this sim, FALSE otherwise.

Notes:
The game does not have any specific code that deals with mission critical ships. It's up to individual scripts to check the status of mission critical ships and take action accordingly.

See also:
iSim.SetMissionCritical


iSim.IsRespawning

Returns true if the given sim is respawning in a multiplayer game.

prototype bool iSim.IsRespawning( hisim sim );

Parameters:
sim : The sim to check.

Return value:
Returns TRUE if the given sim is respawning, false otherwise.


iSim.SetFaction

Sets the faction.

prototype iSim.SetFaction( hisim isim_handle,
                           hfaction faction );

Parameters:
isim_handle : The isim object handle.
faction : The faction handle to attach.

Return value:
None.

See also:
iSim.Faction, iFaction.


iSim.SetIndestructable

Sets or clears the indestructable flag of a sim.

prototype iSim.SetIndestructable( hisim sim, bool flag );

Parameters:
sim : The sim to change.
flag : true or false setting for the sim.

Notes:
Indestructible sims take no system damage, and their hit-points cannot be reduced below 20% of max.

See also:
iSim.IsIndestructable.


iSim.SetMissionCritical

Sets or clears the mission critical flag of a sim.

prototype iSim.SetMissionCritical( hisim sim, bool flag );

Parameters:
sim : The sim to change.
flag : TRUE to set mission critical, FALSE otherwise.

Notes:
Mission critical ships appear as Cyan coloured contacts on the contact list.

The game does not have any specific code that deals with mission critical ships. It's up to individual scripts to check the status of mission critical ships and take action accordingly.

See also:
iSim.IsMissionCritical


iSim.Type

Return the type of sim.

prototype eSimType iSim.Type( hobject sim );

Parameters:
sim : The sim to query.

Return value:
The enum of the type of sim.

See Also:
iSim.eSimType


iSim.FindByNameInSystem

Try to find a specific sim from its name, in a given system

prototype hisim iSim.FindByNameInSystem( string name, string system );

Parameters:
name : The name to search on.
system : The system to search in.

Return value:
A handle to the desired sim, or a null handle.

Notes:
If there are two or more sims with the given name then only the first is returned.

See Also:
iSim.FindByWildcardInSystem, Sim.FindByName, Sim.FindByWildcard


iSim.FindByWildcardInSystem

Returns the set of hisim handles which match the given wildcard in the given system

prototype set iSim.FindByWildcardInSystem( string wildcard, string system );

Parameters:
wildcard : The name to search on.
system : The system to search in.

Return value:
A set of the desired sims.

See Also:
iSim.FindByNameInSystem, Sim.FindByName, Sim.FindByWildcard


iSim.NonPlanetaryInRadius

Returns all non-planetary map entities (habitats and l-points) within the given radius around the given sim except for the given sim.

prototype set iSim.NonPlanetaryInRadius( hsim sim,
                                         float radius );

Parameters:
sim : The sim to query.
radius : The radius around the given sim to search.

Return value:
A set of all habitats and l-points within the given radius around the given sim.

Notes:
The given sim is not included in the set.

SeeAlso:
iSim.SimsInCylinder


iSim.SimsInCone

Get a set of all sims of a particular type in a cone defined by the arguments.

prototype set iSim.SimsInCone( hisim sim,
                   float start_width,
                               float end_width,
                               float length,
                               int type );

Parameters:
sim : The sim to query.
start_width : The start width of the cone in metres.
end_width : The end width of the cone in metres.
length : The length of the cone.
type : The enum of the type to search for.

Return value:
A set of all ships within the given cone around the given sim, excluding the given sim.

Notes:
The given sim is excluded from the set.

SeeAlso:
iSim.SimsInRadius, iSim.SimsInCylinder, iSim.SimsInRadiusFromSet, iSim.SimsInRadiusOfFaction iSim.ShipsInRadius, iSim.NonPlanetaryInRadius, iSim.PlayerHostilesInRadius


iSim.SimsInCylinder

Get a set of all sims of a particular type in a cylinder defined by the arguments.

prototype set iSim.SimsInCylinder( hisim sim,
                       float width,
                                   float length,
                                   int type );

Parameters:
sim : The sim to query.
width : The start width of the cylinder in metres.
length : The length of the cylinder in metres.
type : The enum of the type to search for.

Return value:
A set of all ships within the given cylinder around the given sim, excluding the given sim.

Notes:
The given sim is excluded from the set.

SeeAlso:
iSim.SimsInRadius, iSim.SimsInCone, iSim.SimsInRadiusFromSet, iSim.SimsInRadiusOfFaction iSim.ShipsInRadius, iSim.NonPlanetaryInRadius, iSim.PlayerHostilesInRadius


iSim.SimsInRadius

Get a set of all sims of a particular type in a given radius around a given sim.

prototype set iSim.SimsInRadius( hsim sim,
                  float radius,
                  eSimType type );

Parameters:
sim : The sim to query.
radius : The radius around the given sim to search.
type : The enum of the type to search for.

Return value:
A set of all ships within the given radius around the given sim, excluding the given sim.

Notes:
The given sim is excluded from the set.

SeeAlso:
iSim.SimsInCone, iSim.SimsInCylinder, iSim.SimsInRadiusFromSet, iSim.SimsInRadiusOfFaction iSim.ShipsInRadius, iSim.NonPlanetaryInRadius, iSim.PlayerHostilesInRadius


iSim.SimsInRadiusFromSet

Get a set of all sims from a specified set of sims, of a particular type, and in a given radius around a given sim.

prototype set iSim.ShipsInRadiusFromSet( set set_of_sims
                         hsim sim,
                         float radius,
                         eSimType type );

Parameters:
 set_of_sims : The set of sims to search.
sim : The sim to query.
radius : The radius around the given sim to search.
type : The enum of the type to search for.

Return value:
A set of all ships from the specified set, within the given radius around the given sim, excluding the given sim.

Notes:
The given sim is excluded from the set.

SeeAlso:
iSim.SimsInRadius, iSim.SimsInCone, iSim.SimsInCylinder, iSim.SimsInRadiusOfFaction iSim.ShipsInRadius, iSim.NonPlanetaryInRadius, iSim.PlayerHostilesInRadius


iSim.SimsInRadiusOfFaction

Get a set of all sims of a particular faction in a given radius around a given sim.

prototype set iSim.ShipsInRadius( hsim sim,
                  float radius,
                  hfaction faction );

Parameters:
sim : The sim to query.
radius : The radius around the given sim to search.
faction : The handle of the sim's faction.

Return value:
A set of all ships of the given faction within the given radius around the given sim, excluding the given sim.

Notes:
The given sim is excluded from the set.

SeeAlso:
iSim.SimsInRadius, iSim.SimsInCone, iSim.SimsInCylinder, iSim.SimsInRadiusFromSet, iSim.ShipsInRadius, iSim.NonPlanetaryInRadius, iSim.PlayerHostilesInRadius


iSim.ShipsInRadius

Get a set of all ships in a given radius around a given sim.

prototype set iSim.ShipsInRadius( hsim sim,
                                  float radius );

Parameters:
sim : The sim to query.
radius : The radius around the given sim to search.

Return value:
A set of all ships within the given radius around the given sim.

Notes:
If the given sim is a ship then it will be included in the set.

SeeAlso:
iSim.SimsInRadius, iSim.SimsInCone, iSim.SimsInCylinder, iSim.SimsInRadiusFromSet, iSim.SimsInRadiusOfFaction iSim.NonPlanetaryInRadius, iSim.PlayerHostilesInRadius


iSim.PlayerHostilesInRadius

Get a set of all hostiles of a given type in the given radius around the player.

prototype set iSim.PlayerHostilesInRadius( float radius,
                           eSimType type );

Parameters:
radius : The radius around the given sim to search.
type : The enum of the type to search for.

Return value:
A set of all hostile sims of the given type, within the given radius around the player

SeeAlso:
iSim.SimsInRadius, iSim.SimsInCone, iSim.SimsInCylinder, iSim.SimsInRadiusFromSet, iSim.SimsInRadiusOfFaction iSim.ShipsInRadius, iSim.NonPlanetaryInRadius


iSim.Dock

Instantly dock sim1 to sim2.

prototype bool iSim.Dock( isim sim1, hsim sim2 );

Parameters:
sim1 : A handle to the first sim.
sim : A handle to the second sim.

Return value:
TRUE if the docking was successful, FALSE otherwise.

Notes:
Sim1 and its sim2 must have compatible and free dockports, otherwise docking will be unsuccessful.
If the sim1 has the higher docking priority, the sim1 will move to sim2, otherwise sim1 will move to the sim2.

See Also:
iSim.Undock, iSim.SetDockingLock


iSim.IsDocked

Determines whether or not a given sim is docked to anything.

prototype bool iSim.IsDocked( hsim sim );

Parameters:
sim : The sim to query.

Return value:
Returns true if the given sim is docked to any other sim, false otherwise.

Notes:
Note that this function will return true if any other sim is docked to the given one. This means that a freighter with a cargo pod attached with return true, just the same as if it was docked to a space station.

See also:
iSim.IsDockedTo, iSim.IsDockedToStructure


iSim.IsDockedTo

Determines whether or not a sim is docked to another given sim.

prototype bool iSim.IsDockedTo( hsim sim1,
                                hsim sim2 );

Parameters:
sim1 : The sim to query.
sim2 : The sim to search for.

Return value:
Returns true if the sims are docked together, false otherwise.

See also:
iSim.IsDocked, iSim.IsDockedToStructure


iSim.IsDockedToStructure

Determines whether or not a sim is docked to another given sim or any of the second sim's children.

prototype bool iSim.IsDockedToStructure( hsim sim1,
                                         hsim sim2 );

Parameters:
sim1 : The sim to query.
sim2 : The sim to search for.

Return value:
Returns TRUE if the sims are docked together, FALSE otherwise.

See also:
iSim.IsDocked, iSim.IsDockedTo


iSim.SetDockingLock

Locks or unlocks any docking ports between sim1 and sim2. For this function to be of any use sim1 should be docked to the sim2.

prototype iSim.SetDockingLock( hsim sim1,
                               hsim sim2
                   bool lock );

Parameters:
sim1 : The sim to lock
sim2 : The second sim to lock.
lock : TRUE to lock, FALSE to unlock.

Return value:
None.

Notes:
This function does not undock the two sims it merely makes undocking possible.

See also:
iSim.Dock, iSim.Undock


iSim.UnDock

Undock sim1 from sim2.

prototype bool iSim.Undock( hisim sim1, hisim sim2 );

Parameters:
sim1 : A handle to the first sim.
sim2 : A handle to the second sim.

Return value:
TRUE if the undocking was successful, FALSE otherwise.

Notes:
If the docking lock is set, it must be released for this to work.

See Also:
iSim.Dock, iSim.SetDockingLock


iSim.ActiveWorld

Return the name of the active world ( the world where the player currently resides ) as a string.

prototype string iSim.ActiveWorld();

Parameters:
None.

Return value:
The name of the active world as a string or Loading if the world is currently loading.

See Also:
iSim.WorldName


iSim.CapsuleJump

Cause sim to perform a capsule jump to the given destination. The destination can be in the same system or another system. The exit point will be along the destination jump point's local Z.

prototype iSim.CapsuleJump( hsim sim, hsim destination );

Parameters:
sim : The sim to jump
destination : The sim to jump to.

Return value:
None.

Notes:
The destination does not need to be an L-Point - any sim will do.

See also:
iSim.CapsuleJumpStaggered, CapsuleJumpCustom, IsCapsuleJumping


iSim.CapsuleJumpCustom

Cause sim to perform a capsule jump to the given destination. The destination can be in the same system or another system. The parameters allow you to completely control the exit point and speed.

prototype iSim.CapsuleJumpCustom( hisim sim,
                  hisim destination,
                  float exit_x,
                  float exit_y,
                      float exit_speed );

Parameters:
sim : The sim to jump
destination : The sim to jump to.
exit_x : The x distance from the centre of the destination where the sim appears, in metres.
exit_y : The y distance from the centre of the destination where the sim appears, in metres.
exit_speed : The speed the sim exits capsule space.

Return value:
None.

Notes:
The destination does not need to be an L-Point - any sim will do.
The x and y values are coordinates with the centre of the destination sim at the origin.

See also:
iSim.CapsuleJump, CapsuleJumpCustom, CapsuleJumpStaggered, IsCapsuleJumping


iSim.CapsuleJumpStaggered

Cause sim to perform a capsule jump to the given destination. The destination can be in the same system or another system. The exit point will be randomly staggered to prevent ships appearing in the dead-centre.

prototype iSim.CapsuleJumpStaggered( hsim sim, hsim destination );

Parameters:
sim : The sim to jump
destination : The sim to jump to.

Return value:
None.

Notes:
The destination does not need to be an L-Point - any sim will do.

See also:
iSim.CapsuleJump, CapsuleJumpCustom, IsCapsuleJumping


iSim.IsCapsuleJumping

Returns true if the given sim is capsule jumping.

prototype bool iSim.IsCapsuleJumping( hisim sim );

Parameters:
sim : The sim to check.

Return value:
Returns TRUE if the given sim is capsule jumping, false otherwise.

See also:
iSim.CapsuleJump, CapsuleJumpStaggered


iSim.WorldName

Return the name of the world where the given sim is currently residing.

prototype string iSim.WorldName( hisim sim );

Parameters:
sim : The sim to query.

Return value:
The name of the world of the sim in question as a string or Loading if the world is currently loading.

See Also:
iSim.ActiveWorld


iSim.Attacked

Check if the given sim has been attacked.

prototype iSim.Attacked( hisim sim );

Parameters:
sim : A handle to a sim.

Return value:
TRUE if the sim has been attacked, FALSE otherwise.

Notes:
Using this function resets the 'attacked' flag on the aim.

It's a good idea to use this function once just before you start checking if the sim has been attacked. This ensures the attacked flag is cleared before you start checking if it's been attacked. Otherwise if the attacked flag has already been set before you started checking the sim, your script would assume it had been attacked immediately.

See also:
iSim.LastAttacker


iSim.LastAttacker

Returns the last attacker of a sim.

prototype hisim iSim.LastAttacker( hisim sim );

Parameters:
sim : A handle to a sim.

Return value:
Returns the handle of the sim's last attacker.

Notes:
This function doesn't clear the sim's 'attacked' flag.

See also:
iSim.Attacked


iSim.LockDownWeapons

Locks all weapons down on the sim, preventing them from firing, including any turrets.

prototype bool iSim.LockDownWeapons( hisim sim );

Parameters:
sim : A handle to a sim.

Return value:
TRUE if the locking down was successful, FALSE otherwise.

Notes:
This command doesn't affect the sim's movement, so it's possible to stop a sim firing while it's attacking a target, without affecting the way the sim maneuvers.

See Also:
iSim.WeaponTargetsFromContactList, iSim.WeaponsUseExplicitTarget


iSim.SetHostile

Sets or clears the apparent hostility of a ship to the player.

prototype iSim.SetHostile( hisim sim, bool flag );

Parameters:
sim : The sim to change.
flag : TRUE to set apparently hostile, FALSE to set non-hostile.

Notes:
This function does not affect the actual hostility of the sim, or change its behaviour.


iSim.SetSensorVisibility

Makes a sim visible or invisible on the player's sensors.

prototype iSim.SetSensorVisibility( hisim sim, bool visible );

Parameters:
sim : The sim to change.
visible : TRUE to set visible

Notes:
If a sim is made sensor visible, then that sim will be visible all the time, even if it is out of normal sensor range, or in a different system. Use iSim.SetStandardSensorVisibility to make a sim visible using normal sensor rules.

See also:
iSim.SetStandardSensorVisibility


iSim.SetStandardSensorVisibility

Makes a sim visible or invisible on the player's sensors, using standard sensor visibility rules.

prototype iSim.SetStandardSensorVisibility( hisim sim, bool visible );

Parameters:
sim : The sim to change.
visible : TRUE to set visible, FALSE to set invisible.

Notes:
This command will override the forced visibility of the iSim.SetSensorVisibility command.

See also:
iSim.SetSensorVisibility


iSim.WeaponTargetsFromContactList

Sets all weapon targets from the contact list (generic attack weapon mode).

bool iSim.WeaponTargetFromContactList( hisim sim )

Parameters:
sim : A handle to a sim.

Return value:
TRUE if the function was successful, FALSE otherwise.

Notes:
In this mode a sim's weapons will automatically fire on any hostile target on their contact list that are in their weapon fire arcs.

This command allows the weapons to act independently of the sim's movement, for example a ship could approach a friendly station while automatically firing at any hostiles nearby.

See Also:
iSim.WeaponsUseExplicitTarget, iSim.LockDownWeapons


iSim.WeaponsUseExplicitTarget

Sets all weapons on a sim to attack the given target.

bool iSim.WeaponsUseExplicitTarget( hisim sim, hsim target );

Parameters:
sim : A handle to a sim.
target : The target to attack.

Return value:
TRUE if the function was successful, FALSE otherwise.

Notes:
In this mode a sim's weapons will fire on the given target if it is in any weapon fire arc.

This command allows the weapons to act independently of the sim's movement, for example a sim could approach a friendly station while automatically firing at a hostile cruiser nearby.

See Also:
iSimWeaponTargetsFromContactList, iSim .LockDownWeapons


iSim.AlienInfectionDamage

Return the rate of alien infection damage for the given sim.

prototype float iSim.AlienInfectionDamage( hisim sim );

Parameters:
sim : The sim to check.

Return value:
The alien infection damage rate, in hit-points per second.

See Also:
iSIm.SetAlienInfectionDamage, iSim.AlienInfectionEffect, iSim.IsAlienInfectionEffectOn


iSim.AlienInfectionEffect

Turns on or of alien infection for a given sim.

prototype iSim.AlienInfectionEffect( hisim sim, bool flag );

Parameters:
sim : The sim to change.
flag : TRUE to infect, FALSE otherwise.

See also:
iSIm.SetAlienInfectionDamage, iSim.AlienInfectionDamage, iSim.IsAlienInfectionEffectOn


iSim.IsAlienInfectionEffectOn

Check if the alien infection effect is on.

prototype bool iSim.IsAlienInfectionEffectOn( hisim sim );

Parameters:
sim : The sim to check.

Return value:
Returns TRUE if the given sim is infected, FALSE otherwise.

See Also:
iSIm.SetAlienInfectionDamage, iSim.AlienInfectionEffect, iSim.AlienInfectionDamage


iSim.SetAlienInfectionDamage

Set the damage rate for the alien infected sim.

prototype iSim.SetAlienInfectionDamage( hsim sim,
                                        float rate );

Parameters:
sim : The sim to infect.
rate : The damage rate ( hit points per second ).

Return value:
None.

SeeAlso:
 iSim.AlienInfectionEffect, iSim.AlienInfectionDamage, iSim.IsAlienInfectionEffectOn


iComms/iConversation

The iComms package provides the fundamental tools for communicating with the player. It can be used for general 'colour' communications (such as death rattles from exploding ships or insults from enemy pilots) or for scripting complex conversations.

The iConversation package is a set of helper functions which make scripting conversations easier.

If you are using this package to script a conversation and have not done so before, please examine the sample conversation.

iComms basic functions:

  • iComms.Shout

iComms conversation functions:

  • iComms.Abort
  • iComms.AbortEnd
  • iComms.AddResponse
  • iComms.AddResponseWithCode
  • iComms.Ask
  • iComms.BeginConversation
  • iComms.CanEnd
  • iComms.ClearResponses
  • iComms.EndConversation
  • iComms.IsBusy
  • iComms.IsInConversation
  • iComms.IsOwner
  • iComms.IsSaying
  • iComms.Response
  • iComms.Say

iConversation functions:

  • iConversation.AddResponse
  • iConversation.Ask
  • iConversation.Begin
  • iConversation.End
  • iConversation.OneLiner
  • iConversation.Say

Notes:

The iComms basic API provides simple comms support by allowing other ships to shout unimportant messages to the player.

The iComms advanced conversation API allows complete control over the flow of a conversation. It does not control timing in any way, which allows you more flexibility at the expense of having to write the additional code yourself.

The iConversation package provides the usual means to script conversations. It automatically handles timing issues such as waiting for a phrase to complete, or waiting for a response from the player. This makes scripting most conversations much easier.

Because conversations are implemented with scripts, it is possible to perform other actions directly within a conversation. For example, an enemy ship could be ordered to attack the player if they insulted the ship during a conversation. Alternatively, the player could be given items as a result of a particular conversation choice.


iComms.Shout

Shout a phrase to the player.

prototype iComms.Shout( hobject speaker, string speaker_key, string phrase_key );

Parameters:
 speaker : If this is a a valid handle, then as the phrase will abort if the handle becomes invalid.
speaker_key : The key for the speaker name.
phrase_key : The phrase key for the phrase to say.

Return value:
None.

Notes
If the player is currently in conversation, or if another shouted message is already playing, then the new shouted message will be ignored. This means that shouts should not be used for conveying critical information. They are intended to be a simple means for adding optional colour to encounters without forcing the player to stop and have a chat.

The speaker handle is useful for testing if a speaker ( or the ship / station in which he / she resides ) is still alive. The phrase will abort if the handle becomes null.

If speaker_key is a null string ("") then the name from the speaker's handle object will be used instead, if the object is valid.

The phrase key which identifies the phrase to shout is a string key for a phrase from the localised text database. The player will see/hear the correctly- localised version of the phrase identified by the phrase key, not the phrase key itself. For more information on localised text see the documentation for the Text package.


iComms.Abort

Stops any current conversation immediately, and optionally starts a new conversation.

prototype iComms.Abort( bool start_new_conversation );

Parameters:
start_new_conversation  : Specify whether to start a new conversation or not.

Return value:
None.

Notes
If start_new_conversation is set to true, a new conversation will be started. This has the benefit of locking out any new conversations.

See also:
iComms.AbortEnd


iComms.AbortEnd

Re-enable the conversation after an abort.

prototype iComms.AbortEnd();

Parameters:
None

Return value:
None.

See also:
iComms.Abort


iComms.AddResponse

Add a response to the player's current list of conversation responses.

prototype iComms.AddResponse( string menu_key, string phrase_key );

Parameters:
menu_key : The phrase key for the text to display in the player's response menu.

phrase_key : The phrase key for the response as read by the player character when selected from the menu.

Return value:
None.

Notes
Responses are numbered in the order they are added to the list, starting from one.

The phrase keys which identify the response are string keys for phrases from the localised text database. The player will see/hear the correctly- localised version of the phrase identified by each phrase key, not the phrase key itself. For more information on localised text see the documentation for the Text package.

See also:
iComms.ClearResponses.


iComms.AddResponseWithCode

Add a response to the player's current list of conversation responses, specifying the return code value.

prototype iComms.AddResponse( string menu_key, string phrase_key, int code );

Parameters:
menu_key : The phrase key for the text to display in the player's response menu.
phrase_key : The phrase key for the response as read by the player character when selected from the menu.
code : The value the response will return if it is selected.

Return value:
None.

Notes
The phrase keys which identify the response are string keys for phrases from the localised text database. The player will see/hear the correctly- localised version of the phrase identified by each phrase key, not the phrase key itself. For more information on localised text see the documentation for the Text package.

See also:
iComms.ClearResponses.


iComms.Ask

Ask a question of the player, when the player is in a conversation. The player will then be able to select a response.

prototype iComms.Ask( hobject speaker, string speaker_key, string phrase_key );

Parameters:
speaker : If this is a a valid handle, then as the phrase will abort if the handle becomes invalid.
speaker_key : The key for the speaker name.
phrase_key : The phrase key for the question phrase.

Return value:
None.

Notes
The phrase will be ignored unless the player is currently in a conversation, and no other phrase is playing. The phrase will be displayed using the speaker key for the current conversation.

If the current list of conversation responses is empty, calls to iComms.Ask will be routed to iComms.Say.

When the question phrase is complete, the comms system will present the player with a list of responses and wait for them to select a response. When the response has been selected, the comms system will play the phrase for that response. This behaviour is automatic.

The phrase key which identifies the question phrase is a string key for a phrase from the localised text database. The player will see/hear the correctly- localised version of the phrase identified by the phrase key, not the phrase key itself. For more information on localised text see the documentation for the Text package.


iComms.BeginConversation

Try to begin a conversation with the player.

prototype bool iComms.BeginConversation( string speaker_key );

Parameters:
speaker_key : The phrase key for the name of the speaker. This name is displayed by the subtitles for speaker's phrases during the conversation.

Return value:
If the conversation is successfully started, the return value is true. If the conversation cannot be started, the return value is false. A conversation can always be started unless another conversation is already in progress.

Notes
Any shouted phrases which are still in progress when the conversation is started will be automatically stopped.

The phrase key which identifies the speaker is a string keys for their name as read from the localised text database. The player will see the correctly- localised version of the name identified by each phrase key, not the phrase key itself. For more information on localised text see the documentation for the Text package.

See also:
iComms.EndConversation.


iComms.CanEnd

Check to see if the conversation can be ended safely.

prototype bool iComms.CanEnd();

Parameters:
None.

Return value:
The return value is TRUE if conversation can be ended safely. The conversation can be ended if there's nothing being said that can't be interrupted.

This function is especially important after questions have been asked, where a response is being displayed that the script doesn't know about.

See Also:
iComms.IsInConversation, iComms.IsBusy


iComms.ClearResponses

Clear the player's current response list of all responses.

prototype iComms.ClearResponses();

Parameters:
None.

Return value:
None.

See also:
iComms.AddResponse.


iComms.EndConversation

End the current conversation, if any.

prototype iComms.EndConversation();

Parameters:
None.

Return value:
None.

Notes
When the conversation is ended, the conversation lock is released and other conversations may be started. Only one conversation may be in progress at any one time.

See also:
iComms.BeginConversation.


iComms.IsBusy

Check to see if the communication system is currently busy.

prototype bool iComms.IsBusy();

Parameters:
None.

Return value:
The return value is true if the communications system is busy. The system reports that it is busy if either a phrase is playing, or the player is choosing a response. If the system is not busy, the return value is false.

See Also:
iComms.IsInConversation


iComms.IsInConversation

Check to see if there is a conversation going on, or waiting for the phrase to be printed.

prototype bool iComms.IsInConversation();

Parameters:
None.

Return value:
The return value is true if there is a conversation active. If a conversation is active, or a conversation phrase is being printed the return value is TRUE, and FALSE otherwise.

See Also:
iComms.IsBusy


iComms.IsSaying

Test if a phrase is waiting to be said.

prototype iComms.IsSaying( string phrase_key );

Parameters:
phrase_key : The phrase key for the phrase to say.

Return value:
None.

Notes
The phrase will be ignored unless the player is currently in a conversation, and no other phrase is playing. The phrase will be displayed using the speaker key for the current conversation.

The phrase key which identifies the phrase to say is a string key for a phrase from the localised text database. The player will see/hear the correctly- localised version of the phrase identified by the phrase key, not the phrase key itself. For more information on localised text see the documentation for the Text package.


iComms.IsOwner

Does the current task own the conversation?

prototype bool iComms.IsOwner();

Parameters:
None.

Return value:
TRUE if the current task owns the current conversation.


iComms.Say

Say a phrase to the player, when the player is in a conversation.

prototype iComms.Say( hobject speaker, string speaker_key, string phrase_key );

Parameters:
speaker : If this is a a valid handle, then as the phrase will abort if the handle becomes invalid.
speaker_key : The key for the speaker name.
phrase_key : The phrase key for the phrase to say.

Return value:
None.

Notes
The speaker handle is useful for testing if a speaker ( or the ship / station in which he / she resides ) is still alive. The phrase will abort if the handle becomes null.

If speaker_key is a null string ("") then the name from the speaker's handle object will be used instead, if the object is valid.

The phrase will be ignored unless the player is currently in a conversation, and no other phrase is playing. The phrase will be displayed using the speaker key for the current conversation.

The phrase key which identifies the phrase to say is a string key for a phrase from the localised text database. The player will see/hear the correctly- localised version of the phrase identified by the phrase key, not the phrase key itself. For more information on localised text see the documentation for the Text package.


iConversation.AddResponse

Add a response to the player's current list of conversation responses.

prototype iConversation.AddResponse( string menu_key, string phrase_key );

Parameters:
menu_key : The phrase key for the text to display in the player's response menu.

phrase_key : The phrase key for the response as read by the player character when selected from the menu.

Return value:
None.

Notes
Responses are numbered in the order they are added to the list, starting from one.

The response list is automatically cleared by iConversation.Begin at the start of a conversation, and also by iConversation.Ask following each question.

The phrase keys which identify the response are string keys for phrases from the localised text database. The player will see/hear the correctly- localised version of the phrase identified by each phrase key, not the phrase key itself. For more information on localised text see the documentation for the Text package.

See also:
iConversation.Begin, iConversation.Ask.


iConversation.Ask

Ask a question of the player, when the player is in a conversation.

prototype int iConversation.Ask( hobject speaker, string speaker_key, string phrase_key );

Parameters:
speaker : If this is a a valid handle, then as the phrase will abort if the handle becomes invalid.
speaker_key : The key for the speaker name.
phrase_key : The phrase key for the question phrase.

Return value:
The return value is the number of the player's chosen response, or zero if there are no responses in the list.

Notes
This function will wait until any phrase in progress finishes before starting the new phrase. It will not return until the new phrase has finished, the player has selected a response, and the player's response phrase has also finished.

The question phrase will be displayed using the speaker key for the current conversation.

The speaker handle is useful for testing if a speaker ( or the ship / station in which he / she resides ) is still alive. The phrase will abort if the handle becomes null.

If speaker_key is a null string ("") then the name from the speaker's handle object will be used instead, if the object is valid.

The phrase key which identifies the question phrase is a string key for a phrase from the localised text database. The player will see/hear the correctly- localised version of the phrase identified by the phrase key, not the phrase key itself. For more information on localised text see the documentation for the Text package.


iConversation.Begin

Begin a conversation with the player.

prototype iConversation.Begin();

Parameters:
None

Return value:
None.

Notes
This function will not return until the conversation has been successfully started.

Any shouted phrases which are still in progress when the conversation is started will be automatically stopped.

See also:
iConversation.End.


iConversation.End

End the current conversation.

prototype iConversation.End();

Parameters:
None.

Return value:
None.

Notes
When the conversation is ended, the conversation lock is released and other conversations may be started. Only one conversation may be in progress at any one time.

See also:
iConversation.Begin.


iConversation.OneLiner

Say a phrase to the player, starting and ending the conversation automatically.

prototype iConversation.OneLiner( hobject speaker, string speaker_key, string phrase_key );

Parameters:
speaker : If this is a a valid handle, then as the phrase will abort if the handle becomes invalid.
speaker_key : The key for the speaker name.
phrase_key : The phrase key for the phrase to say.

Return value:
None.

Notes
This function starts and ends a conversation automatically, and is useful for situations when you have a single line of dialogue in a conversation.

This function will wait until any phrase in progress finishes before starting the new phrase. It will not return until the new phrase has finished.

The speaker handle is useful for testing if a speaker ( or the ship / station in which he / she resides ) is still alive. The phrase will abort if the handle becomes null.

If speaker_key is a null string ("") then the name from the speaker's handle object will be used instead, if the object is valid.

The phrase key which identifies the phrase to say is a string key for a phrase from the localised text database. The player will see/hear the correctly- localised version of the phrase identified by the phrase key, not the phrase key itself. For more information on localised text see the documentation for the Text package.


iConversation.Say

Say a phrase to the player, when the player is in a conversation.

prototype iConversation.Say( hobject speaker, string speaker_key, string phrase_key );

Parameters:
speaker : If this is a a valid handle, then as the phrase will abort if the handle becomes invalid.
speaker_key : The key for the speaker name.
phrase_key : The phrase key for the phrase to say.

Return value:
None.

Notes
This function will wait until any phrase in progress finishes before starting the new phrase. It will not return until the new phrase has finished.

The speaker handle is useful for testing if a speaker ( or the ship / station in which he / she resides ) is still alive. The phrase will abort if the handle becomes null.

If speaker_key is a null string ("") then the name from the speaker's handle object will be used instead, if the object is valid.

The phrase key which identifies the phrase to say is a string key for a phrase from the localised text database. The player will see/hear the correctly- localised version of the phrase identified by the phrase key, not the phrase key itself. For more information on localised text see the documentation for the Text package.


Sample conversation script using iConversation

Description

I-War 2 conversations are described with small script task functions which implement the conversation as a small Pog program. This means that there is no new conversation file format to learn, and the conversation language is very powerful. The packages iComms and iConversation provide the functions to control the conversation.

This example uses iConversation since it provides a simplified API for conversations, although it does not provide quite as much flexibility as iComms. For more information on the packages and their difference, see the appropriate package documentation.

To implement a conversation, write a task function with the name of the conversation, and start this task running. The conversation will start as soon as any current conversation is complete.

Sample code

package SampleConversation;

//
// We need to use the iConversation package to implement the
// conversation. We also use iInventory to give the player
// items depending on what they ask for in the conversation.
//
uses iConversation, iInventory;

//
// Export our conversation task function.
//
provides JafsChat;

//
// JafsChat
//
// A short conversation with Jafs whereby the player may
// acquire some choice items.
//
task JafsChat()
{
    // Start the conversation.
    iConversation.Begin( "name_jafs" );

    //
    // Add the responses the player may use
    //

    // Response 1
    iConversation.AddResponse(
        "a1m1_jafs_chat_weapons_menu",
        "a1m1_jafs_chat_weapons_response" );

    // Response 2
    iConversation.AddResponse(
        "a1m1_jafs_chat_software_menu",
        "a1m1_jafs_chat_software_response" );

    // Response 3
    iConversation.AddResponse(
        "a1m1_jafs_chat_nothing_menu",
        "a1m1_jafs_chat_nothing_response" );

    // Ask the player a question and switch on their response.
    switch ( iConversation.Ask( "a1m1_jafs_chat_what_do_you_want" ) )
    {
        case 1 :
            // Player selected "Weapons"
            iConversation.Say( "a1m1_jafs_chat_heres_a_pbc" );

            // Give them a PBC
            iInventory.Add( "ini:/cargo/high/weapons/heavy_pbc", 1 );
            break;

        case 2 :
            // Player selected "Software"
            iConversation.Say( "a1m1_jafs_chat_try_this_autopilot" );

            // Give them an autopilot.
            iInventory.Add( "ini:/cargo/expensive/data/autopilot", 1 );
            break;

        default :
            // Player selected "Nothing"
            iConversation.Say( "a1m1_jafs_ok_mate" );
    }

    // Say bye
    iConversation.Say( "a1m1_jaffs_chat_im_off_to_the_effrit" );

    // Finish the conversation.
    iConversation.End();

} // JaffsChat

Screenshots

This is what the player might see during this conversation. Note that the phrases displayed on the screen are the correct localised text, not the phrase keys which are used in the conversation.


iDirector

This package allows the control of cameras, and the creation of cut-scenes using the in-game 3D engine.

Type definitions:

  • eCamera

Functions:

General

  • Begin
  • End
  • IsBusy
  • SetCaption

Focus
The director mode cameras need to look at or focus on a subject. These commands deal with setting the focus for the current director camera.

  • Focus
  • SecondaryFocus

  • SetFocus

  • SetSecondaryFocus

Cameras
These commands deal with setting up the various cameras available.

  • Camera
  • SetCamera

Dolly
Dolly functions are used to move cameras in straight lines. This is useful for panning and zooming shots. Dolly camera functions rely on a special sim known as a dolly.

  • AttachDollyToSim
  • CreateDolly
  • DollyLookForward.
  • SetDollyCamera
  • SetDirection
  • UseDollyOrientation
  • UseSimOrientation

Field Of View

The Field Of View functions allow you to zoom the cameras.

  • SetFieldOfView
  • SetInterpolateFieldOfView

Fading

The fading functions allow you to fade the screen in and out for scene transitions.

  • FadeIn
  • FadeOut

Obituary

The obituary functions are a special set designed for when the player's ship is destroyed.

  • Obituary
  • IsObituaryView

Notes:

Most director functions only work when the game is in director mode.

Helper functions for creating cutscenes can be found in the scripted package iCutsceneUtilities. See the iCutsceneUtilities header file for details.


iDirector.eCamera

This enumeration is used for the different camera types.

enum eCamera
{
    CAM_None,

    // Internal camera
    CAM_Internal,

    // Internal camera without cockpit
    CAM_InternalNoCockpit,

    // Internal no HUD
    CAM_InternalNoHUD,

    // Chase camera
    CAM_Chase,

    // Chase camera with headup
    CAM_Arcade,

    // External camera
    CAM_External,

    // Target external camera
    CAM_TargetExternal,

    // Tactical camera
    CAM_Tactical,

    // Inverse tactical camera
    CAM_InverseTactical,

    // Flyby camera
    CAM_Flyby,

    // Drop camera
    CAM_Drop,

    // Distant drop camera
    CAM_DistantDrop,

    // Two-shot camera (focus on left, target on right)
    CAM_TwoShot,

    // Two-shot camera (foci reversed)
    CAM_InverseTwoShot,

    // Conversation camera (focus on left, target on right)
    CAM_Conversation,

    // Bridge shot camera (look at the front of the primary)
    CAM_BridgeShot,

    // Target bridge shot camera (look at the front of the secondary)
    CAM_TargetBridgeShot,

    // Contact camera (used to render target MFD)
    CAM_Contact,

    // Dolly camera, primary is the camera, secondary is looked at
    CAM_Dolly,

    // Tactical camera with no HUD
    CAM_TacticalNoHUD,

    // Distant bridge shot
    CAM_DistantBridgeShot,

    // Number of cameras.
    eCameraCount
};

Notes:
The declaration of this enumeration can be found in iDirector.h.


iDirector.Begin

Starts an in-game cut-scene ( also known as director mode), and sets director mode active. If a director mode is already active this command does nothing.

prototype iDirector.Begin()

Parameters:
None

Return value:
None

Notes
When this command is called, black bars will appear at the top and bottom of the screen, though the camera view will not change.

It's important to note that in director mode all scripts will proceed as normal, so take care to ensure that the player, and other script tasks do not interfere with your cut-scene.

When a cut-scene is playing all script bound keys are disabled.

See also:
iDirector.End, iDirector.IsBusy


iDirector.End

Ends an in-game cut-scene ( also known as director mode), and de-activates director mode. If a director mode is not active this command does nothing.

prototype iDirector.Begin()

Parameters:
None

Return value:
None

See also:
iDirector.Begin, iDirector.IsBusy


iDirector.IsBusy

Checks to see if the director mode is active.

prototype bool iDirector.IsBusy()

Parameters:
None

Return value:
TRUE if director mode is busy, FALSE if not.

See also:
iDirector.Begin, iDirector.End


iDirector.SetCaption

Displays a director mode caption.

prototype iDirector.SetCaption( string caption, float time );

Parameters:
caption : The text key for the caption.
time : The time to display the caption.

Return value:
None.

Notes
This command must be called in director mode.

The caption is displayed at the bottom of the visible viewing screen. Captions do not text wrap, so ensure that your caption does not extend off the visible screen area when the game is in a 640x480 screen mode.


iDirector.Focus

Return the sim the director camera is currently focused on.

prototype bool iDirector.Focushttp://www.invisibledream.com/reviews/pc/iwar2/index3.php()

Parameters:
None

Return value:
A handle to a sim, or none if no sim is focused.

See also:
iDirector.SetFocus, iDirector.SecondaryFocus, iDirector.SetSecondaryFocus


iDirector.SecondaryFocus

Some cameras use two focuses. The primary ( as defined with iDirector.SetFocus) and a secondary (as defined by iDirector.SetSecondaryFocus). This command returns the sim the director camera's secondary focus is focused on.

prototype bool iDirector.SecondaryFocus()

Parameters:
None

Return value:
A handle to a sim, or none if no sim is focused.

See also:
iDirector.Focus, iDirector.SetFocus, iDirector.SetSecondaryFocus


iDirector.SetFocus

Sets the focus of the current camera.

prototype iDirector.SetFocus( hsim focus );

Parameters:
focus : The sim to focus on.

 Return value:
None.

Notes
This command must be called in director mode.

The focus must be a valid sim. This command will have no effect on cameras that don't use a focus.

See also:
iDirector.Focus, iDirector.SecondaryFocus, iDirector.SetSecondaryFocus


iDirector.SetSecondaryFocus

Some cameras use two focuses. The primary ( as defined with iDirector.SetFocus) and a secondary. This command sets the secondary focus of the current camera.

prototype iDirector.SetSecondaryFocus( hsim focus );

Parameters:
focus : The sim to focus on.

 Return value:
None.

Notes
This command must be called in director mode.

The focus must be a valid sim. This command will have no effect on cameras that don't use a focus.

See also:
iDirector.Focus, iDirector.SetFocus, iDirector.SecondaryFocus


iDirector.Camera

Return the camera that director mode is currently using

prototype eCamera iDirector.Camera()

Parameters:
None

Return value:
The enum of the current camera.

See also:
eCamera, SetCamera


iDirector.SetCamera

Sets the director mode camera.

prototype iDirector.SetCamera( eCamera camera );

Parameters:
camera : The camera to use.

 Return value:
None.

Notes
This command must be called in director mode.

The new camera will use the same focus as the previous camera.

See also:
eCamera, iDirector.Camera, iDirector.SetFocus


iDirector.AttachDollyToSim

Attach a dolly to a sim. This is useful to get a dolly to move around on a non-linear path. ( For example, following a ship ).

prototype iDirector.AttachDollyToSim( hsim dolly, hsim sim );

Parameters:
dolly : The sim to use as a dolly.
sim : The sim to attach the dolly to.

 Return value:
None.

Notes
The dolly must be a valid sim.
The sim can be any sim, but it makes sense to use a sim that can move around, such as a ship.
The dolly will be detached from any other sim it is attached to.

See also:
iDirector.CreateDolly, iDirector.SetDollyCamera, iDirector.SetDirection, iDirector.UseDollyOrientation, iDirector.UseSimOrientation, iDirector.DollyLookForward.


iDirector.CreateDolly

Creates a sim to use as a dolly camera.

prototype hsim iDirector.CreateDolly()

Parameters:
None

Return value:
A handle to the dolly camera.

Notes:
 The dolly sim is used with iDirector.SetDollyCamera to perform various camera moves.

See also:
iDirector.SetDollyCamera, iDirector.SetDirection, iDirector.AttachDollyToSim, iDirector.UseDollyOrientation, iDirector.UseSimOrientation, iDirector.DollyLookForward.


iDirector.DollyLookForward

Force the dolly to look forward.

prototype iDirector.DollyLookForward( hsim dolly );

Parameters:
dolly : The dolly sim.

 Return value:
None.

Notes
The dolly must be a valid sim.

See also:
iDirector.CreateDolly, iDirector.SetDollyCamera, iDirector.SetDirection, iDirector.AttachDollyToSim, iDirector.UseDollyOrientation, iDirector.UseSimOrientation


iDirector.SetDollyCamera

Set a sim to use as a dolly camera.

prototype iDirector.SetDollyCamera( hsim dolly );

Parameters:
dolly : The sim to use as a dolly.

 Return value:
None.

Notes
The dolly must be a valid sim. Any sim can be used, but it is recommended you use the command iDirector.CreateDolly.

See also:
See also:
iDirector.CreateDolly, iDirector.SetDirection, iDirector.AttachDollyToSim, iDirector.UseDollyOrientation, iDirector.UseSimOrientation, iDirector.DollyLookForward.


iDirector.SetDirection

Move a dolly camera between two sims, in the given time. Used to create panning moves.

prototype iDirector.SetDirection( hsim dolly, hsim start, hsim finish, float time, float acc_time );

Parameters:
dolly : The sim to use as a dolly.
start : The sim to where the dolly starts
finish : The sim where the dolly finishes.
time : The time it takes to move the dolly from start to finish.
time_acc : The time it takes to accelerate / decelerate the dolly. (Used to smoothly start and stop the dolly).

Return value:
None.

Notes
The dolly must be a valid sim.
The start and finish sims can be any sim type, but it's recommended you use waypoints.

See also:
See also:
iDirector.CreateDolly, iDirector.SetDollyCamera, iDirector.AttachDollyToSim, iDirector.UseDollyOrientation, iDirector.UseSimOrientation, iDirector.DollyLookForward.


iDirector.UseDollyOrientation

Orientation of the dolly view is normally defined by what is being looked at (the primary focus). Calling this with true will allow the orientation to be picked up from the dolly sim orientation. Calling with false will reset to the normal behaviour. This is useful if you want the dolly camera to be oriented in a particular, fixed, direction.

prototype iDirector.UseDollyOrientation( hsim dolly, bool dolly_orientation );

Parameters:
dolly : The dolly sim.
dolly_orientation : TRUE to use the dolly orientation, FALSE to use the primary focus orientation.

 Return value:
None.

Notes
The dolly must be a valid sim.

See also:
iDirector.CreateDolly, iDirector.SetDollyCamera, iDirector.SetDirection, iDirector.AttachDollyToSim, iDirector.UseSimOrientation, iDirector.DollyLookForward.


iDirector.UseSimOrientation

Orientation of the dolly view is normally defined by what is being looked at (the primary focus). Calling this function will set the dolly orientation from a given sim.

prototype iDirector.UseSimOrientation( hsim dolly, hsim sim );

Parameters:
dolly : The dolly sim.
sim : The sim to use the orientation from.

 Return value:
None.

Notes
The dolly must be a valid sim. Any sim can be used, but it is recommended you use the command iDirector.CreateDolly.

See also:
iDirector.CreateDolly, iDirector.SetDollyCamera, iDirector.SetDirection, iDirector.AttachDollyToSim, iDirector.UseDollyOrientation, iDirector.DollyLookForward.


iDirector.SetFieldOfView

Sets the field of view of the current camera. This effectively allows you change the zoom factor of the camera.

prototype iDirector.SetFieldOfView( float fov );

Parameters:
fov : The field of view value.

 Return value:
None.

Notes
The fov value is a floating point number. A typical value for an external camera is 1.2

See also:
iDirector.SetInterpolateFieldOfView


iDirector.SetInterpolateFieldOfView

Interpolate the current camera's field of view between two angles over a time period. This effectively allows you zoom the camera in and out in real-time.

prototype iDirector.SetInterpolateFieldOfView( float from_fov, float to_fov, float time );

Parameters:
from_fov : The start field of view.
to_fov : The finish field of view.
time : The interpolation time.

 Return value:
None.

Notes
The fov values are floating point numbers. A typical value for an external camera is 1.2

See also:
iDirector.SetFieldOfView


iDirector.FadeIn

Fade-in the camera view from the specified colour, over the specified time. This is useful for scene transitions.

prototype iDirector.FadeIn( float time, float red, float green, float blue );

Parameters:
time : The fade in time.
red : The red value of the fade in colour.
green : The green value of the fade in colour.
blue : The blue value of the fade in colour.

 Return value:
None.

Notes
The colour values are between 0 and 1, where 1 is the maximum colour value.

See also:
iDirector.FadeOut


iDirector.FadeOut

Fade the camera view down to the specified fade out colour, over the specified time. This is useful for scene transitions.

prototype iDirector.FadeOut( float time, float red, float green, float blue );

Parameters:
time : The fade out time.
red : The red value of the fade out colour.
green : The green value of the fade out colour.
blue : The blue value of the fade out colour.

 Return value:
None.

Notes
The colour values are between 0 and 1, where 1 is the maximum colour value.

See also:
iDirector.FadeIn


iDirector.IsObituaryView

Checks to see if the obituary view is active.

prototype bool iDirector.IsObituaryView()

Parameters:
None

Return value:
TRUE if obituary view is active, FALSE if not.

See also:
iDirector.Obituary


iDirector.Obituary

Sets director mode into obituary mode, which displays a special view of the player ship, while displaying an obituary caption.

prototype iDirector.Obituary( string caption );

Parameters:
caption : The text key for the caption.

Return value:
None.

Notes:
The caption is displayed at the bottom of the visible viewing screen. Captions do not text wrap, so ensure that your caption does not extend off the visible screen area when the game is in a 640x480 screen mode.

See Also:
 iDirector.IsObituaryView


iMultiplay

This package provides the Pog functionality for multiplayer Games.

Type definitions:

  • eBcastMessageType
  • eScoreSortMode

Functions:

Creating and Modifying Multiplayer Ships and Objects

These functions create or modify Multiplayer ships and objects. Note that some of these functions are useful for non-multiplayer ships.

  • AddAIShip
  • AddAmmo
  • AddHealth
  • AddPowerupWeapon
  • AddPowerupWeaponDirect
  • Autorepair
  • ChangeMaxSpeed
  • ChangeWeaponFireRate
  • InstallAIPilot
  • InstallAIPilotX
  • LinkShipWeapons
  • RemoteLinkTo
  • RemovePowerupWeapons
  • RemovePowerupWeaponDirect
  • SetShip Limits
  • Set TransmitFlag
  • Set UpdateFlag
  • SeverRemoteLinkTo
  • UnlinkShipWeapons

Multiplayer Game Commands

  • AddBotEndGame Info
  • EndGame
  • SendScores
  • Set ForRespawn

Multiplayer Game Properties

  • AIBotsCount
  • AIBotsSkill Level
  • Frag Limit
  • IsClient
  • IsGameEnded
  • MapINI
  • PackageINI
  • SetFragLimit
  • SetGameType
  • SetPlayerShip
  • SetTimeLimit
  • TimeLimit
  • UseAIBots

Server Commands

These commands are used exclusively on the server side scripts.

  • GetServerMap List
  • GetServerPackageList
  • GetServerShip List
  • IsServerAppSpawned
  • ServerAppSpawn
  • ServerAppTerminate
  • ServerBroadcastMessage
  • ServerIP
  • ServerMapListItem
  • ServerMapListItemshort
  • ServerPackageListItem
  • ServerPackageListItemshort
  • ServerPlayer DiedCount
  • ServerPlayer FlagsCount
  • ServerPlayerFragCount
  • ServerPlayerIP
  • ServerPlayerList
  • ServerPlayerPing
  • ServerPlayerTeam
  • ServerRandomPlayer
  • ServerRejectclient
  • ServerResetScores
  • ServerResetTeams
  • ServerSendPlayerMessage
  • ServerSendUserMessage
  • Server SetPlayerDiedCount
  • Server SetPlayerFlagsCount
  • Server SetPlayerFragsCount
  • Server SetPlayerTeam
  • Server SetSortMode
  • Server SetWinningTeam
  • ServerShip ListItem

Server Browser Commands

  • ServerBrowserAddress
  • ServerBrowserBegin Internet
  • ServerBrowserBegin LAN
  • ServerBrowserCount
  • ServerBrowser Create
  • ServerBrowser Destroy
  • ServerBrowser DisplayItem
  • ServerBrowserGame type
  • ServerBrowserMapName
  • ServerBrowser MaxPlayers
  • ServerBrowserPing
  • ServerBrowserPlayer s
  • ServerBrowser Port
  • ServerBrowser ProtocoVersion
  • ServerBrowserSession Index
  • ServerBrowserSession IndexFromName
  • ServerBrowserSession Name
  • ServerBrowser SetPogFunctions
  • ServerBrowser UpdateComplete
  • ServerBrowser ValidateKey
  • ServerBrowser Version

Client Commands

These commands are used exclusively on the client side scripts.

  • ClientAddRespawnEffect
  • ClientBroadcastMessage
  • ClientBroadcastTeamMessage
  • ClientEndGameInfoCount
  • ClientEndGameInfoDied
  • Client endGameInfoFlags
  • Client endGameInfoFrags
  • Client endGameInfoName
  • Client endGameInfoTeam
  • ClientFragCount
  • ClientIsTeamGame
  • Client KilledCount
  • ClientLastAddress
  • ClientLastSession
  • ClientOpenHUDTauntBox
  • ClientPlayerList
  • ClientPlayer Stats
  • Client RejectedCount
  • Client ResetScores
  • Client Say
  • Client SendUserMessage
  • ClientSet LastAddress
  • ClientSet LastSession
  • ClientSetTeamGame
  • Client UID

Client Options

These commands deal with multiplayer client options settings.

  • ClientOptionsDefaultTaunt
  • ClientOptionsHostSession
  • ClientOptionsLoad
  • ClientOptionsName
  • ClientOptionsSave
  • ClientOptionsServerAddress
  • ClientOptionsServerAIBots
  • ClientOptionsServerAIBotsCount
  • ClientOptionsServerAIBotsSkill
  • ClientOptionsServerArcadeMode
  • ClientOptionsServerFragLimit
  • ClientOptionsServerMap
  • ClientOptionsServerName
  • ClientOptionsServerPackage
  • ClientOptionsServerTimeLimit
  • ClientOptionsSetHostSession
  • ClientOptionsSetName
  • ClientOptionsSetServerAddress
  • ClientOptionsSetServerAIBots
  • ClientOptionsSetServerAIBotsCount
  • ClientOptionsSetServerAIBotsSkill
  • ClientOptionsSetServerArcadeMode
  • ClientOptionsSetServerFragLimit
  • ClientOptionsSetServerMap
  • ClientOptionsSetServerName
  • ClientOptionsSetServerPackage
  • ClientOptionsSetServerTimelimit
  • ClientOptionsSetShip
  • ClientOptionsShip

Network Commands

  • Network IsLobbySession
  • Network ProtocolCount
  • Network ProtocolItem
  • Network Reset
  • Network SessionCount
  • Network SessionItem
  • Network SessionMaxPlayers
  • Network SessionPlayers
  • Network SetProtocol

Map Cycling

  • Client RequestedToCycle
  • ClientSet RequestedToCycle


iMultiplay.eBcastMessageType

This enumeration is used to define the multiplayer broadcast message types.

enum eBcastMessageType
{
    BMT_None,
    BMT_Conversation,
    BMT_Info,
    BMT_Event,
    BMT_Audio
};

Notes:
The declaration of this enumeration can be found in iMultiplay.h.


iMultiplay.eScoreSortMode

This enumeration is used to define the multiplayer scoring sort modes.

enum eScoreSortMode
{
    SSM_Frags,
    SSM_Flags
};

Notes:
The declaration of this enumeration can be found in iMultiplay.h.


iMultiplay.AddAIShip

Creates a new ship on the server which is propagated to the clients. The ship is placed next to the marker sim offset by x, y, z.

prototype bool iMultiplay.AddAIShip ( hship ship,
                      hsim marker,
                      float x,
                      float y,
                      float z);

Parameters:
ship : The ship to create.
marker : The marker where to place the ship in relation to.
x, y, z : The offset where to place the ship.

Return Value:
 TRUE if the ship was added, FALSE otherwise.

See also:
iMultiplay.InstallAIPilot, iMultiplay.InstallAIPilotX


iMultiplay.AddAmmo

Add an amount to all ammo based weapons on a ship, i.e. missiles, gatling cannon bolts.

prototype iMultiplay.AddAmmo( hship ship, int amount );

Parameters:
ship : The ship to add ammo to.
amount : The amount of ammo to add.

Return Value:
None


iMultiplay.AddHealth

Multiply a ship's health by a percentage.

prototype iMultiplay.AddHealth( hship ship, float percentage_change );

Parameters:
ship : The ship to change the health for.
percentage_change : The amount to change by.

Return Value:
None


iMultiplay.AddPowerupWeapon

Adds a power-up weapon to a multiplayer ship.

prototype iMultiplay.AddPowerupWeapon( hship ship, hisim powerup );

Parameters:
ship : A handle to a ship.
powerup : A handle to a powerup.

Return Value:
None.

See also:
iMultiplay.RemovePowerupWeapon, iMultiplayer.AddPowerupweaponDirect


iMultiplay.AddPowerupWeaponDirect

Adds a power-up weapon to a multiplayer ship, using the specified weapon subsim url.

prototype iMultiplay.AddPowerupWeapon( hship ship, string resource_ini );

Parameters:
ship : A handle to a ship.
resource_ini : A resource URL of a weapon.

Return Value:
None.

Notes:
Multiplayer ships tend to use AI weapons, so that heat mechanics are not a problem.

See also:
iMultiplay.RemovePowerupWeaponDirect, iMultiplay.RemovePowerupWeapons, iMultiplayer.AddPowerupWeapon


iMultiplay.AutoRepair

Turn on / off autorepair for the specified ship.

prototype iMultiplay.AutoRepair( hship ship, bool repair );

Parameters:
ship : The ship to change the autorepair for.
repair : TRUE for autorepair on, FALSE for autorepair off.

Return Value:
None


iMultiplay.ChangeMaxSpeed

Change a ship's maximum speed.

prototype iMultiplay.ChangeMaxSpeed( hship ship, float percentage_change );

Parameters:
ship : The ship to change the max speed for.
percentage_change : The amount to change by.

Return Value:
None


iMultiplay.ChangeWeaponFireRate

Multiply a ship's weapons firing rate by a percentage.

prototype iMultiplay.ChangeWeaponFireRate( hship ship, float percentage_change );

Parameters:
ship : The ship to change the firing rate for.
percentage_change : The amount to change by.

Return Value:
None


iMultiplay.InstallAIPilot

Installs a default pilot in a multiplayer ship.

prototype iMultiplay.InstallAIPilot( hship ship );

Parameters:
ship : A handle to a ship.

Return Value:
None.

See also:
iMultiplay.AddAIShip, iMultiplay.InstallAIPilotX


iMultiplay.InstallAIPilotX

Installs a customised AI pilot in a multiplayer ship.

prototype iMultiplay.InstallAIPilotX( hship ship,
                      float ignore_fight,
                      float fight_flee,
                      float self_preserve,
                                      string fight_func,
                      string flee_func,
                                      string ignore_func,
                      string self_preserve_func );

Parameters:
ship : A handle to a ship.
ignore_fight : The ignore or fight (lowermost) threat ratio.
fight_flee : The fight or flee (uppermost) threat ratio.
self_preserve : Self preservation hitpoint/max hitpoint ratio.
fight_func : Alternative script function to call if fight is signalled.
flee_func : Alternative script function to call if flee is signalled.
ignore_func : Alternative script function to call if ignore is signalled.
self_preserve_func : Alterantive script function to call if self preservation is signalled.

Return Value:
None.

See also:
iMultiplay.AddAIShip, iMultiplay.InstallAIPilot


iMultiplay.LinkShipWeapons

Links a ships weapons so they fire simultaneously.

prototype iMultiplay.LinkShipWeapons( hship ship );

Parameters:
ship : A handle to a ship.

Return Value:
None.

Notes:
Only identical weapons can be linked together, e.g. two pbcs.
This command is also useful in single player scripts for forcing weapons linking on AI and remote piloted ships.

See also:
iMultiplay.UnlinkShipWeapons


iMultiplay.RemoteLinkTo

Link the player pilot to the specified ship.

prototype iMultiplay.RemoteLinkTo( hship );

Parameters:
ship : The ship to link to.

Return Value:
 None.

See also:
iMultiplay.SeverRemoteLinkTo


iMultiplay.RemovePowerupWeapons

Remove the powerup weapons from a ship, optionally returning a list of removed weapons.

prototype list iMultiplay.AddPowerupWeapon( hship ship, bool produce_list );

Parameters:
ship : A handle to a ship.
produce_list : TRUE to return a list of powerups removed from the ship. FALSE otherwise.

Return Value:
A list of the powerups removed.

Notes:
This command is useful if you want to spawn powerups from a dead ship.

See also:
iMultiplayer.RemovePowerupWeaponDirect, iMultiplayer.AddPowerupWeapon, iMultiplayer.AddPowerupWeaponDirect


iMultiplay.RemovePowerupWeaponDirect

Remove a power-up weapon from a multiplayer ship, using the specified weapon subsim url.

prototype iMultiplay.RemovePowerupWeapon( hship ship, string resource_ini );

Parameters:
ship : A handle to a ship.
resource_ini : A resource URL of a weapon.

Return Value:
None.

See also:
iMultiplay.RemovePowerupWeapons, iMultiplayer.AddPowerupWeapon, iMultiplayer.AddPowerupWeaponDirect


iMultiplay.SetShipLimits

Configures the ship for multiplayer.

prototype iMultiplay.SetShipLimits( hship ship );

Parameters:
ship : A handle to a ship.

Return Value:
None.

Notes:
This command must be used on every ship used in multiplayer.

See also:
iMultiplay.AddAIShip


iMultiplay.SetTransmissionFlag

Add a sim that is propagated from server to client, but doesn't have to send periodic update info. Useful for adding static sims like asteroids and other space furniture.

prototype iMultiplay.SetTransmissionFlag( hisim sim, bool flag );

Parameters:
sim : The sim to change.
flag : TRUE to send update info, FALSE to not send info.

Return Value:
None.

See also:
iMultiplay.SetUpdateFlag


iMultiplay.SetUpdateFlag

Add a sim that is propagated from server to client, but doesn't have to send periodic update info. However the server can still send updates. Useful for adding static sims like asteroids and other space furniture.

prototype iMultiplay.SetUpdateFlag( hisim sim, bool flag );

Parameters:
sim : The sim to change.
flag : TRUE to send info, FALSE to not send info.

Return Value:
None.

See also:
iMultiplay.SetTransmitFlag


iMultiplay.SeverRemoteLinkTo

Sever the player pilot to the specified ship.

prototype iMultiplay.SeverRemoteLinkTo( hship );

Parameters:
ship : The ship to sever the link to.

Return Value:
 None.

See also:
iMultiplay.RemoteLinkTo


iMultiplay.UnLinkShipWeapons

Unlink a ship's weapons

prototype iMultiplay.UnlinkShipWeapons( hship ship );

Parameters:
ship : A handle to a ship.

Return Value:
None.

See also:
iMultiplay.LinkShipWeapons


iMultiplay.AddBotEndGameInfo

Augment score table with AI Bot info.

prototype iMultiplay.AddBotEndGameInfo( string name,
                    string team,
                    int frags,
                    int flags,
                    int died );

Parameters:
name : The name of the bot.
team : The team the bot belonged to.
frags : The number of kills the bot made.
flags : Optional custom flags
died : How many times the bot died.

Return Value:
None.


iMultiplay.EndGame

Inform the server to end the game session. This also brings up the score table.

prototype iMultiplay.EndGame();

Parameters:
None.

Return Value:
None.


iMultiplay.SendScores

Send the scores to the player ship.

prototype iMultiplay.SendScores( hship ship );

Parameters:
ship : A handle to the player ship.

Return Value:
None.


iMultiplay.SetForRespawn

Notify the server to send a respawn event for the client who owns this sim.

prototype iMultiplay.SetForRespawn( hisim sim );

Parameters:
sim : A handle to a sim.

Return Value:
None.


iMultiplay.AIBotsCount

Find the number of AI bots in the current game.

prototype int iMultiplay.AIBotsCount();

Parameters:
None.

Return Value:
The number of AI Bots.

See Also:
iMultiplay.AIBotsSkillLevel, iMultiplay.UseAIBots


iMultiplay.AIBotsSkillLevel

Find the skill level for the AI bots.

prototype float iMultiplay.AIBotsSkillLevel();

Parameters:
None.

Return Value:
The skill level.

See Also:
iMultiplay.AIBotsCount, Multiplay.UseAIBots


iMultiplay.FragLimit

Find out the frag limit for the current multiplayer game.

prototype int iMultiplay.FragLimit();

Parameters:
None.

Return Value:
The frag limit.

See Also:
iMultiplay.SetTimeLimit


iMultiplay.IsClient

Check if we are running as a client.

prototype bool iMultiplay.IsClient();

Parameters:
None

Return Value:
TRUE if running as a client, FALSE if running as a server.


iMultiplay.IsGameEnded

Called by a client to see if the game has ended.

prototype bool iMultiplay.IsGameEnded();

Parameters:
None

Return Value:
TRUE if the game has ended, FALSE otherwise.


iMultiplay.MapINI

Returns the current map ini file.

prototype string iMultiplay.MapINI();

Parameters:
None

Return Value:
The map ini file resource request.

See Also:
iMultiplay.PackageINI


iMultiplay.PackageINI

Returns the current package ini file, i.e. "ini:/multiplay/packages/tdm" etc.

prototype string iMultiplay.PackageINI();

Parameters:
None

Return Value:
The package ini file resource request.

See Also:
iMultiplay.MapINI


iMultiplay.SetFragLimit

Set the number of kills it takes to win a multiplayer game.

prototype iMultiplay.SetFragLimit( int frags );

Parameters:
frags : The frag limit

Return Value:
None.

See also:
iMultiplay.FragLimit


iMultiplay.SetGameType

Set the game type for a multiplayer game. This string is queried by the server browser and is used as a key to localise the text.

prototype iMultiplay.SetGameType( string type );

Parameters:
type : The game type as a string.

Return Value:
None.

Notes:
The game type is a unique string identifying the game type. Current game types are:

DM

Deathmatch

CTF

Capture the flag

TDM

Team Deathmatch

MT

Mine Tag

TMT

Team Mine Tag

BT Bomb Tag

Additional game types may be created as necessary.


iMultiplay.SetPlayerShip

Sets the ship's NetRole to NR_ClientSim and changes its name. This will cause the sim to be propogated first to the server and then from the server to any other clients on the network as and when they join the game.

The list of players is also updated to include the new local player and remove any old instance of the player ship

prototype bool iMultiplay.SetPlayerShip( hship ship, string playername, hship old_ship );

Parameters:
ship : The ship to change to.
playername : The player name.
old_ship : The ship to remove.

Return Value:
None


iMultiplay.SetTimeLimit

Set the time limit for a multiplayer game.

prototype iMultiplay.SetTimeLimit( int seconds );

Parameters:
seconds : The time limit in seconds.

Return Value:
None.

See also:
iMultiplay.TimeLimit


iMultiplay.TimeLimit

Find out the time limit for the current multiplayer game.

prototype int iMultiplay.TimeLimit();

Parameters:
None.

Return Value:
The time limit in seconds.

See Also:
iMultiplay.SetTimeLimit


iMultiplay.UseAIBots

Check if AI bots are used in the current game.

prototype bool iMultiplay.UseAIBots();

Parameters:
None.

Return Value:
TRUE if AI bots are used in the current game, false otherwise.

See Also:
iMultiplay.AIBotsCount, iMultiplay.AIBotsSkillLevel


iMultiplay.GetServerMapList

Constructs the list of multiplayer package ini filenames, returning the current count.

prototype int iMultiplay.GetServerMapList( string package_name );

Parameters:
package_name : The name of the package to get the list for.

Return Value:
The count of multiplayer maps found.

See Also:
iMultiplay.ServerMapListItem


iMultiplay.GetServerPackageList

Constructs the list of multiplayer package ini filenames, returning the current count.

prototype int iMultiplay.GetServerPackageList();

Parameters:
None

Return Value:
The count of multiplayer package ini filenames found.

See Also:
iMultiplay.ServerPackageListItem


iMultiplay.GetServerShipList

Constructs the list of multiplayer ship ini filenames, returning the current count.

prototype int iMultiplay.GetServerShipList();

Parameters:
None

Return Value:
The count of multiplayer ships found.

See Also:
iMultiplay.ServerShipListItem


iMultiplay.IsServerAppSpawned

Check if the server application is active.

prototype bool iMultiplay.IsServerAppSpawned();

Parameters:
None

Return Value:
TRUE if the server application is active, FALSE otherwise.

See Also:
iMultiplay.ServerAppSpawn, iMultiplay.ServerAppTerminate


iMultiplay.ServerAppSpawn

Spawn an extra copy of the server application.

prototype iMultiplay.ServerAppSpawn( string parameters );

Parameters:
parameters : Any specific options for the server application.

Return Value:
None

See Also:
iMultiplay.IsServerAppSpawned, iMultiplay.ServerAppTerminate


iMultiplay.ServerAppTerminate

Check if the server application is active.

prototype bool iMultiplay.NetworkServerAppTerminate();

Parameters:
None

Return Value:
None

See Also:
iMultiplay.ServerAppSpawn, iMultiplay.IsServerAppSpawned


iMultiplay.ServerBroadcastMessage

Send a message to all clients.

prototype iMultiplay.ServerBroadcastMessage( hsim sender,
                         string message,
                                             eBcastMessageType message_type );

Parameters:
sender : The sim from which the message is sent.
message : The message.
message_type : The type of message.

Return Value:
None.

See Also:
 eBcastMessageType, iMultiplay.ServerSendPlayerMessage, iMultiplay.ServerSendUserMessage


iMultiplay.ServerIP

Return the IP address of the server.

prototype int iMultiplay.ServerIP();

Parameters:
player : A handle to a player sim.

Return Value:
The ping time of the player sim

See Also:
 iMultiplayer.ServerPlayerIP


iMultiplay.ServerMapListItem

Get the map name of the specified entry in the map list.

prototype string iMultiplay.ServerMapListItem( int item );

Parameters:
item : The package item number.

Return Value:
The name of the map

See Also:
iMultiplay.ServerMapListItemShort, iMultiplay.GetServerMapList


iMultiplay.ServerMapListItemShort

Get a shortened map name of the specified entry in the map list.

prototype string iMultiplay.ServerMapListItemShort( int item );

Parameters:
item : The package item number.

Return Value:
The shortened name of the map.

See Also:
iMultiplay.ServerMapListItem


iMultiplay.ServerPackageListItem

Get the package name of the specified entry in the package list.

prototype string iMultiplay.ServerPackageListItem( int item );

Parameters:
item : The package item number.

Return Value:
The name of the package.

See Also:
iMultiplay.ServerPackageListItemShort, iMultiplay.GetServerPackageList


iMultiplay.ServerPackageListItemShort

Get a shortened name of the specified entry in the package list.

prototype string iMultiplay.ServerPackageListItemShort( int item );

Parameters:
item : The package item number.

Return Value:
The shortened name.

See Also:
iMultiplay.ServerPackageListItem


iMultiplay.ServerPlayerDiedCount

Return the number of times the specified player has died.

prototype int iMultiplay.ServerPlayerDiedCount(  hsim player );

Parameters:
player : A handle to a player sim.

Return Value:
The number of times the player has died.

See also:
iMultiplay.ServerSetPlayerDiedCount


iMultiplay.ServerPlayerFlagsCount

Return the number of times the specified player has captured a flag.

prototype int iMultiplay.ServerPlayerFlagsCount(  hsim player );

Parameters:
player : A handle to a player sim.

Return Value:
The number of times the player has captured a flag..

See Also:
 iMultiplayer.ServerSetPlayerFlagsCount


iMultiplay.ServerPlayerFragCount

Return the number of kills the specified player has scored.

prototype int iMultiplay.ServerPlayerFragCount( hsim player );

Parameters:
player : A handle to a player sim.

Return Value:
The number of kills the player has scored.

See Also:
 iMultiplayer.ServerSetPlayerFragsCount


iMultiplay.ServerPlayerIP

Return the IP address of the specified player sim.

prototype int iMultiplay.ServerPlayerIP( hsim player );

Parameters:
player : A handle to a player sim.

Return Value:
The ping time of the player sim

See Also:
 iMultiplayer.ServerIP, iMultiplayer.ServerPlayerPing


iMultiplay.ServerPlayerList

Return a list of player ships in the multiplayer game.

prototype list iMultiplay.ServerPlayerList();

Parameters:
None

Return Value:
A list of player ships.


iMultiplay.ServerPlayerPing

Return the ping of the specified player sim.

prototype int iMultiplay.ServerPlayerPing( hsim player );

Parameters:
player : A handle to a player sim.

Return Value:
The ping time of the player sim.

See Also:
 iMultiplayer.ServerPlayerIP


iMultiplay.ServerPlayerTeam

Return the team associated with the specified player

prototype string iMultiplay.ServerPlayerTeam( hsim player );

Parameters:
player : A handle to a player sim.

Return Value:
The name of the player's team.

See Also:
 iMultiplayer.ServerSetPlayerTeam


iMultiplay.ServerRandomPlayer

Return a random player from the current list of players.

prototype hsim iMultiplay.ServerRandomPlayer();

Parameters:
None

Return Value:
A player ship sim.


iMultiplay.ServerRejectClient

Reject a client from the game, with the specified reason.

prototype iMultiplay.ServerRejectClient( hsim player, string reason );

Parameters:
player : The client's player sim.
reason : The text for the rejection message.

Return Value:
None.


iMultiplay.ServerResetScores

Resets the frag and killed count for all players.

prototype iMultiplay.ServerResetScores();

Parameters:
None

Return Value:
None.

See Also:
 iMultiplayer.ServerResetTeams


iMultiplay.ServerResetTeams

Reset the team list.

prototype iMultiplay.ServerResetTeams();

Parameters:
None

Return Value:
None.

See Also:
 iMultiplayer.ServerResetScores


iMultiplay.ServerSendPlayerMessage

Send a message to a particular player.

prototype iMultiplay.ServerSendPlayerMessage( int player,
                         string message,
                                             eBcastMessageType message_type );

Parameters:
player : The index of the player.
message : The message.
message_type : The type of message.

Return Value:
None.

See Also:
 eBcastMessageType, iMultiplay.ServerBroadcastMessage, iMultiplay.ServerSendUserMessage


iMultiplay.ServerSendUserMessage

Send a user defined message to the server.

prototype iMultiplay.ServerSendUserMessage( int id,
                        hsim sim1,
                                            hsim sim2,
                                            string data );

Parameters:
id : A unique identifier for the message.
sim1 : The he handle of the sim associated with the message event, or none if it's not a sim specific message.
sim2 : The handle of an additional sim, or none if not needed.
data : Any additional data, in string format.

Return Value:
None.

Notes:
The message is sent to all clients that have a local copy of sim1.

See Also:
 iMultiplay.ServerBroadcastMessage, iMultiplay.ServerSendPlayerMessage


iMultiplay.ServerSetPlayerDiedCount

Set the number times the specified player has died.

prototype iMultiplay.ServerSetPlayerDiedCount( hsim player, int count );

Parameters:
player : The player
count : The number times the player has died.

Return Value:
None.

See also:
iMultiplay.ServerPlayerDiedCount


iMultiplay.ServerSetPlayerFlagsCount

Set the number of flags captured by the specified player.

prototype iMultiplay.ServerSetPlayerFlagsCount( hsim player, int count );

Parameters:
player : The player
count : The number of flags captured.

Return Value:
None.

See also:
iMultiplay.ServerPlayerFlagsCount


iMultiplay.ServerSetPlayerFragsCount

Set the number of kills scored by the specified player.

prototype iMultiplay.ServerSetPlayerFragsCount( hsim player, int count );

Parameters:
player : The player
count : The number kills.

Return Value:
None.

See also:
iMultiplay.ServerPlayerFragCount


iMultiplay.ServerSetPlayerTeam

Set the team for the specified player.

prototype iMultiplay.ServerSetPlayerTeam( hisim player, string team_name );

Parameters:
player : The player to set the team for.
team_name : The name of the team.

Return Value:
None.

See Also:
 iMultiplayer.ServerPlayerTeam


iMultiplay.ServerSetSortMode

Set the player scores sort mode.

prototype iMultiplay.ServerSetSortMode( eScoreSortMode mode );

Parameters:
mode : The score mode.

Return Value:
None

See Also:
iMultiplay.eScoreSortMode


iMultiplay.ServerSetWinningTeam

Set the winning team name, which is then sent to all clients in the end game info message.

prototype iMultiplay.ServerSetWinningTeam( string team_name );

Parameters:
team_name : The name of the team.

Return Value:
None.


iMultiplay.ServerShipListItem

Get the ini file name of the specified entry in the ship list.

prototype string iMultiplay.ServerPackageListItem( int item );

Parameters:
item : The ship list item number.

Return Value:
The resource request for the ship.

See Also:
iMultiplay.GetServerShipList


iMultiplay.ServerBrowserAddress

Get the address information for the specified browser item.

prototype string iMultiplay.ServerBrowserAddress( int item );

Parameters:
item : The number of the item.

Return Value:
A string containing the information.


iMultiplay.ServerBrowserBeginInternet

Start the browser search for Internet sessions.

prototype iMultiplay.ServerBrowserBeginInternet();

Parameters:
None

Return Value:
None

See Also:
iMultiplay.ServerBrowserBeginLAN


iMultiplay.ServerBrowserBeginLAN

Start the browser search for LAN sessions.

prototype iMultiplay.ServerBrowserBeginLAN();

Parameters:
None

Return Value:
None

See Also:
iMultiplay.ServerBrowserBeginInternet


iMultiplay.ServerBrowserCount

Count the number of sessions displayed in the session browser.

prototype int iMultiplay.ServerBrowserCount();

Parameters:
None

Return Value:
The number of sessions in the browser.


iMultiplay.ServerBrowserCreate

Create the session browser.

prototype iMultiplay.ServerBrowserCreate();

Parameters:
None

Return Value:
None

See Also:
iMultiplay.ServerBrowserDestroy


iMultiplay.ServerBrowserDestroy

Destroy the session browser.

prototype iMultiplay.ServerBrowserDestroy();

Parameters:
None

Return Value:
None

See Also:
iMultiplay.ServerBrowserCreate


iMultiplay.ServerBrowserDisplayItem

Get the display information for the specified browser item.

prototype string iMultiplay.ServerBrowserDisplayItem( int item );

Parameters:
item : The number of the item.

Return Value:
A string containing the information.


iMultiplay.ServerBrowserGameType

Get the game type for the specified browser item.

prototype string iMultiplay.ServerBrowserGameType( int item );

Parameters:
item : The number of the item.

Return Value:
A string containing the information.


iMultiplay.ServerBrowserMapName

Get the map name for the specified browser item.

prototype string iMultiplay.ServerBrowserMapName( int item );

Parameters:
item : The number of the item.

Return Value:
A string containing the information.


iMultiplay.ServerBrowserMaxPlayers

Get the maximum number of players for the specified browser item.

prototype int iMultiplay.ServerBrowserMaxPlayers( int item );

Parameters:
item : The number of the item.

Return Value:
An int containing the information.


iMultiplay.ServerBrowserPing

Get the ping for the specified browser item.

prototype int iMultiplay.ServerBrowserPing( int item );

Parameters:
item : The number of the item.

Return Value:
An int containing the information.


iMultiplay.ServerBrowserPlayers

Get the number of players for the specified browser item.

prototype int iMultiplay.ServerBrowserPlayers( int item );

Parameters:
item : The number of the item.

Return Value:
An int containing the information.


iMultiplay.ServerBrowserPort

Get the port information for the specified browser item.

prototype int iMultiplay.ServerBrowserPort( int item );

Parameters:
item : The number of the item.

Return Value:
An int containing the information.


iMultiplay.ServerBrowserProtocolVersion

Find out our protocol version information.

prototype int iMultiplay.ServerBrowserProtocolVersion();

Parameters:
None

Return Value:
An int containing the version..


iMultiplay.ServerBrowserSessionIndex

Get the session index for the specified browser item.

prototype int iMultiplay.ServerBrowserSessionIndex( int item );

Parameters:
item : The number of the item.

Return Value:
An int containing the information.


iMultiplay.ServerBrowserSessionIndexFromName

Get the session index for the specified IP address and session name.

prototype int iMultiplay.ServerSessionIndexFromName( string ip_address,
                                                     string session_name );

Parameters:
ip_address : The IP address to find the index from.
session_name : The session_name to find the index from.

Return Value:
An int containing the index.


iMultiplay.ServerBrowserSessionName

Get the session name for the specified browser item.

prototype string iMultiplay.ServerBrowserSessionName( int item );

Parameters:
item : The number of the item.

Return Value:
A string containing the information.


iMultiplay.ServerBrowserSetPogFunctions

Set the Pog functions that will be used when the server browser is updated or completed.

prototype iMultiplay.ServerBrowserSetPogFunctions( string update_func,
                                                   string complete_func );

Parameters:
update_func : The Pog function to use when the browser is updated.
complete_func :The Pog function to use when the browser completes.

Return Value:
None.


iMultiplay.ServerBrowserUpdateComplete

Check if the browser update is complete.

prototype bool iMultiplay.ServerBrowserUpdateComplete();

Parameters:
None

Return Value:
TRUE if the browser update is complete, FALSE otherwise.


iMultiplay.ServerBrowserValidateKey

Validate the specified Multiplayer CD key.

prototype bool iMultiplay.ServerBrowserValidateKey( string key );

Parameters:
key : A string containing the multiplayer key.

Return Value:
TRUE if the key is valid, FALSE otherwise.


iMultiplay.ServerBrowserVersion

Get the version information for the specified browser item.

prototype string iMultiplay.ServerBrowserVersion( int item );

Parameters:
item : The number of the item.

Return Value:
A string containing the information.


iMultiplay.ClientAddRespawnEffect

Creates the default respawn effect.

prototype bool iMultiplay.ClientAddRespawnEffect( hship ship );

Parameters:
ship : The ship to add the respawn effect to.

Return Value:
None


iMultiplay.ClientBroadcastMessage

Send a message to all other players on the network.

prototype iMultiplay.ClientBroadcastMessage( hsim sender,
                         string message,
                                             eBcastMessageType message_type );

Parameters:
sender : The sim from which the message is sent.
message : The message.
message_type : The type of message.

Return Value:
None.

See Also:
 eBcastMessageType, iMultiplay.ClientBroadcastTeamMessage, iMultiplayer.ServerBroadcastMessage


iMultiplay.ClientBroadcastTeamMessage

Send a message to all other team members on the network.

prototype iMultiplay.ClientBroadcastTeamMessage( hsim sender,
                             string message,
                                                 eBcastMessageType message_type );

Parameters:
sender : The sim from which the message is sent.
message : The message.
message_type : The type of message.

Return Value:
None.

See Also:
 eBcastMessageType, iMultiplay.ClientBroadcastMessage, iMultiplayer.ServerBroadcastMessage


iMultiplay.ClientEndGameInfoCount

Return the number of clients on the end game info list.

prototype int iMultiplay.ClientEndGameInfoCount();

Parameters:
None.

Return Value:
The number of clients on the end game info list.

See Also:
 iMultiplay.GameInfoName, iMultiplay.GameInfoTeam, iMultiplay.GameInfoFrags, iMultiplay.GameInfoFlags, iMultiplay.GameInfoDied


iMultiplay.ClientEndGameInfoDied

Return the died count of a specified client in the end game info list.

prototype int iMultiplay.ClientEndGameInfoDied( int client );

Parameters:
client : The number of the client in the end game info list.

Return Value:
The number of times the client died.

See Also:
 iMultiplay.GameInfoCount, iMultiplay.GameInfoName, iMultiplay.GameInfoTeam, iMultiplay.GameInfoFrags, iMultiplay.GameInfoFlags


iMultiplay.ClientEndGameInfoFlags

Return the flag captures of a specified client in the end game info list.

prototype int iMultiplay.ClientEndGameInfoFlags( int client );

Parameters:
client : The number of the client in the end game info list.

Return Value:
The number of flag captures.

See Also:
 iMultiplay.GameInfoCount, iMultiplay.GameInfoName, iMultiplay.GameInfoTeam, iMultiplay.GameInfoFrags, iMultiplay.GameInfoDied


iMultiplay.ClientEndGameInfoFrags

Return the frags of a specified client in the end game info list.

prototype int iMultiplay.ClientEndGameInfoFrags( int client );

Parameters:
client : The number of the client in the end game info list.

Return Value:
The number of frags.

See Also:
 iMultiplay.GameInfoCount, iMultiplay.GameInfoName, iMultiplay.GameInfoTeam, iMultiplay.GameInfoFrags, iMultiplay.GameInfoDied


iMultiplay.ClientEndGameInfoName

Return the name of a specified client in the end game info list.

prototype string iMultiplay.ClientEndGameInfoName( int client );

Parameters:
client : The number of the client in the end game info list.

Return Value:
The name of the client.

See Also:
 iMultiplay.GameInfoCount, iMultiplay.GameInfoTeam, iMultiplay.GameInfoFrags, iMultiplay.GameInfoFlags, iMultiplay.GameInfoDied


iMultiplay.ClientEndGameInfoTeam

Return the team of a specified client in the end game info list.

prototype string iMultiplay.ClientEndGameInfoTeam( int client );

Parameters:
client : The number of the client in the end game info list.

Return Value:
The name of the team.

See Also:
 iMultiplay.GameInfoCount, iMultiplay.GameInfoName, iMultiplay.GameInfoFrags, iMultiplay.GameInfoFlags, iMultiplay.GameInfoDied


iMultiplay.ClientFragCount

Returns this client's frag count.

prototype int iMultiplay.ClientFragCount();

Parameters:
None.

Return Value:
The number of times the player has fragged.

See Also:
 iMultiplayer.ServerPlayerFragCount, iMultiplay.ClientKilledCount


iMultiplay.ClientIsTeamGame

Check if we are running a team game..

prototype bool iMultiplay.ClientIsTeamGame();

Parameters:
None

Return Value:
TRUE if running as a team game, FALSE otherwise.

See Also:
iMultiplay.ClientSetTeamGame


iMultiplay.ClientKilledCount

Returns this client's killed score.

prototype int iMultiplay.ClientKilledCount();

Parameters:
None.

Return Value:
The number of times the player has been killed.

See Also:
 iMultiplayer.ServerPlayerDiedCount, iMultiplay.ClientFragCount


iMultiplay.ClientLastAddress

This function returns the stored last address setting for map cycling.

prototype string iMultiplay.ClientLastAddress();

Parameters:
None

Return Value:
The last address.

See Also:
iMultiplay.ClientSetLastAddress


iMultiplay.ClientLastSession

This function remembers the last session for map cycling.

prototype string iMultiplay.ClientLastSession();

Parameters:
None

Return Value:
The last session.

See Also:
iMultiplay.ClientSetLastSession


iMultiplay.ClientOpenHUDTauntBox

Add the 'taunt' edit box to the HUD. The edit box is initialised with the default_text string.

prototype iMultiplay.ClientOpenHUDTauntBox( string default_text );

Parameters:
default_text : The default text.

Return Value:
None


iMultiplay.ClientPlayerList

Return a list of all clients.

prototype list iMultiplay.ClientPlayerList();

Parameters:
None

Return Value:
A list of the client sims.


iMultiplay.ClientPlayerStats

Returns frag / killed info for all players in the last session

prototype string iMultiplay.ClientPlayerStats();

Parameters:
None.

Return Value:
A string containing html formatted info.


iMultiplay.ClientRejectedCount

Return the amount of times the client has been rejected by the server.

prototype int iMultiplay.ClientRejectedCount();

Parameters:
None

Return Value:
The number of rejections.


iMultiplay.ClientResetScores

Resets the frag and killed count for this client

prototype iMultiplay.ClientResetScores();

Parameters:
None

Return Value:
None.

See Also:
 iMultiplayer.ServerResetScores


iMultiplay.ClientSay

Use the Comms system to send a message to the HUD.

prototype iMultiplay.ClientSay( hsim sender,
                string message );

Parameters:
sender : The sim from which the message is sent.
message : The message.

Return Value:
None.


iMultiplay.ClientSendUserMessage

Send a user defined message to the server.

prototype iMultiplay.ClientSendUserMessage( int id,
                        hsim sim1,
                                            hsim sim2,
                                            string data );

Parameters:
id : A unique identifier for the message.
sim1 : The he handle of the sim associated with the message event, or none if it's not a sim specific message.
sim2 : The handle of an additional sim, or none if not needed.
data : Any additional data, in string format.

Return Value:
None.

Notes:
The message is sent to all clients that have a local copy of sim1.

See Also:
 iMultiplay.ClientBroadcastMessage, iMultiplay.ClientBroadcastTeamMessage, iMultiplay.ServerSendUserMessage


iMultiplay.ClientSetLastAddress

Set the last address for map cycling.

prototype iMultiplay.ClientSetLastAddress( string address );

Parameters:
address : The address to set.

Return Value:
None.

See also:
iMultiplay.ClientLastAddress


iMultiplay.ClientSetLastSession

Set the last session for map cycling.

prototype iMultiplay.ClientSetLastSession( string session );

Parameters:
session : The session to set.

Return Value:
None.

See also:
iMultiplay.ClientLastSession


iMultiplay.ClientSetTeamGame

Set the client's team game status.

prototype iMultiplay.ClientSetTeamGame( bool team_game );

Parameters:
team_game : TRUE for a team game, FALSE otherwise.

Return Value:
None

See Also:
iMultiplay.ClientIsTeamGame


iMultiplay.ClientUID

Returns the client's user ID number.

prototype iMultiplay.ClientUID();

Parameters:
None

Return Value:
None.


iMultiplay.NetworkIsLobbySession

Check if the client was started from a lobby session.

prototype bool iMultiplay.NetworkIsLobbySession();

Parameters:
None

Return Value:
TRUE if the client was started from a lobby session, FALSE otherwise.


iMultiplay.NetworkProtocolCount

Return the number of supported protocols

prototype int iMultiplay.NetworkProtocolCount();

Parameters:
None

Return Value:
The number of protocols.

See Also:
iMultiplay.NetworkProtocolItem, iMultiplay.NetworkSetProtocol


iMultiplay.NetworkProtocolItem

Return the string name of a specified protocol item.

prototype string iMultiplay.NetworkProtocolItem( int item );

Parameters:
item : The number of the protocol item.

Return Value:
The protocol name, e.g. "DirectPlay TCP/IP Protocol"

See Also:
iMultiplay.NetworkProtocolCount, iMultiplay.NetworkSetProtocol


iMultiplay.NetworkReset

Reset the network device.

prototype iMultiplay.NetworkReset();

Parameters:
None

Return Value:
None


iMultiplay.NetworkSessionCount

Return the number of server sessions active for the selected protcol.

prototype int iMultiplay.NetworkSessionCount();

Parameters:
None

Return Value:
The number of sessions.

See Also:
iMultiplay.NetworkSessionItem, iMultiplay.NetworkSessionPlayers, iMultiplay.NetworkSessionMaxPlayers


iMultiplay.NetworkSessionItem

Return the string name of a specified session.

prototype string iMultiplay.NetworkSessionItem( int item );

Parameters:
item : The number of the session item.

Return Value:
The name of the session.

See Also:
iMultiplay.NetworkSessionCount, iMultiplay.NetworkSessionPlayers, iMultiplay.NetworkSessionMaxPlayers


iMultiplay.NetworkSessionMaxPlayers

Return the maximum number of players for a specified session.

prototype int iMultiplay.NetworkSessionMaxPlayers( int item );

Parameters:
item : The number of the session item.

Return Value:
The maximum number of players for the session.

See Also:
iMultiplay.NetworkSessionCount, iMultiplay.NetworkSessionItem, iMultiplay.NetworkSessionPlayers


iMultiplay.NetworkSessionPlayers

Return the number of players in a specified session.

prototype int iMultiplay.NetworkSessionPlayers( int item );

Parameters:
item : The number of the session item.

Return Value:
The number of players in the session.

See Also:
iMultiplay.NetworkSessionCount, iMultiplay.NetworkSessionItem, iMultiplay.NetworkSessionMaxPlayers


iMultiplay.NetworkSetProtocol

Set the specified protocol.

prototype iMultiplay.NetworkSetProtocol( int item );

Parameters:
item : The number of the protocol item to set

Return Value:
None

See Also:
iMultiplay.NetworkProtocolCount, iMultiplay.NetworkProtocolItem


iMultiplay.ClientOptionsDefaultTaunt

Return the default taunt string from the default taunt number.

prototype iMultiplay.ClientOptionsDefaultTaunt( int taunt_number );

Parameters:
taunt_number : The number of the taunt.

Return Value:
The taunt string.


iMultiplay.ClientOptionsHostSession

Return the setting of the Host Session multiplayer option.

prototype bool iMultiplay.ClientOptionsHostSession();

Parameters:
None.

Return Value:
TRUE to host session, FALSE otherwise.

See Also:
iMultiplay.ClientOptionsSetHostSession


iMultiplay.ClientOptionsLoad

Loads the multiplayer option settings on a client.

prototype iMultiplay.ClientOptionsLoad();

Parameters:
None.

Return Value:
None.

See Also:
iMultiplay.ClientOptionsSave


iMultiplay.ClientOptionsName

Return the name, as set in the multiplayer options.

prototype string iMultiplay.ClientOptionsName();

Parameters:
None.

Return Value:
The name as stored in the options.

See Also:
iMultiplay.ClientOptionsSetName


iMultiplay.ClientOptionsSave

Saves the multiplayer option settings on a client.

prototype iMultiplay.ClientOptionsSave();

Parameters:
None.

Return Value:
None.

See Also:
iMultiplay.ClientOptionsLoad


iMultiplay.ClientOptionsServerAddress

Return the setting of the Server Address multiplayer option.

prototype string iMultiplay.ClientOptionsServerAddress();

Parameters:
None.

Return Value:
The host address as set in the multiplayer options.

See Also:
iMultiplay.ClientOptionsSetServerAddress


iMultiplay.ClientOptionsServerAIBots

Return the setting of the AI Bots multiplayer option.

prototype bool iMultiplay.ClientOptionsServerAIBots();

Parameters:
None.

Return Value:
The AI Bots setting as set in the multiplayer options.

See Also:
iMultiplay.ClientOptionsSetServerAIBots


iMultiplay.ClientOptionsServerAIBotsCount

Return the setting of the AI Bots count multiplayer option.

prototype float iMultiplay.ClientOptionsServerAIBotsCount();

Parameters:
None.

Return Value:
The AI Bots count setting as set in the multiplayer options.

See Also:
iMultiplay.ClientOptionsSetServerAIBotsCount


iMultiplay.ClientOptionsServerAIBotsSkill

Return the setting of the AI Bots skill multiplayer option.

prototype float iMultiplay.ClientOptionsServerAIBotsSkill();

Parameters:
None.

Return Value:
The AI Bots skill setting as set in the multiplayer options.

See Also:
iMultiplay.ClientOptionsServerSetAIBotsSkill


iMultiplay.ClientOptionsServerArcadeMode

Return the setting of the ArcadeMode multiplayer option.

prototype bool iMultiplay.ClientOptionsServerArcadeMode();

Parameters:
None.

Return Value:
TRUE to for arcade mode, FALSE otherwise.

See Also:
iMultiplay.ClientOptionsSetServerArcadeMode


iMultiplay.ClientOptionsServerFragLimit

Return the server frag limit, as set in the multiplayer options.

prototype int iMultiplay.ClientOptionsServerFragLimit();

Parameters:
None.

Return Value:
The server frag limit as stored in the options.

See Also:
iMultiplay.ClientOptionsSetServerFragLimit


iMultiplay.ClientOptionsServerMap

Return the server map, as set in the multiplayer options.

prototype string iMultiplay.ClientOptionsServerMap();

Parameters:
None.

Return Value:
The server map as stored in the options.

See Also:
iMultiplay.ClientOptionsSetServerMap


iMultiplay.ClientOptionsServerName

Return the server name, as set in the multiplayer options.

prototype string iMultiplay.ClientOptionsServerName();

Parameters:
None.

Return Value:
The server name as stored in the options.

See Also:
iMultiplay.ClientOptionsSetServerName


iMultiplay.ClientOptionsServerPackage

Return the server Pog package name, as set in the multiplayer options.

prototype string iMultiplay.ClientOptionsServerPackage();

Parameters:
None.

Return Value:
The server Pog package name as stored in the options.

See Also:
iMultiplay.ClientOptionsSetServerPackage


iMultiplay.ClientOptionsServerTimeLimit

Return the server time limit, as set in the multiplayer options.

prototype int iMultiplay.ClientOptionsServerTimeLimit();

Parameters:
None.

Return Value:
The server time limit as stored in the options.

See Also:
iMultiplay.ClientOptionsSetServerTimeLimit


iMultiplay.ClientOptionsSetHostSession

Change the Host Session setting in the multiplayer options.

prototype iMultiplay.ClientOptionsSetHostSession( bool host );

Parameters:
host : TRUE to host session, FALSE otherwise.

Return Value:
None

See Also:
iMultiplay.ClientOptionsHostSession


iMultiplay.ClientOptionsSetName

Set the name in the multiplayer options.

prototype iMultiplay.ClientOptionsSetName( string name );

Parameters:
name : The name to set.

Return Value:
None

See Also:
iMultiplay.ClientOptionsName


iMultiplay.ClientOptionsSetServerAddress

Change the Host Session setting in the multiplayer options.

prototype iMultiplay.ClientOptionsSetServerAddress( string address );

Parameters:
address : The server address as a string.

Return Value:
None

See Also:
iMultiplay.ClientOptionsServerAddress


iMultiplay.ClientOptionsSetServerAIBots

Change the AI Bots setting in the multiplayer options.

prototype iMultiplay.ClientOptionsSetServerAIBots( bool bots );

Parameters:
bots : TRUE to use AI Bots FALSE otherwise.

Return Value:
None

See Also:
iMultiplay.ClientOptionsServerAIBots


iMultiplay.ClientOptionsSetServerAIBotsCount

Change the AI Bots count setting in the multiplayer options.

prototype iMultiplay.ClientOptionsSetServerAIBotsCount( int count );

Parameters:
count : The number of AI bots.

Return Value:
None

See Also:
iMultiplay.ClientOptionsServerAIBotsCount


iMultiplay.ClientOptionsSetServerAIBotsSkill

Change the AI Bots skill setting in the multiplayer options.

prototype iMultiplay.ClientOptionsSetServerAIBotsSkill( float skill );

Parameters:
skill : The skill of the AI bots as a float in the range 0 to 1.

Return Value:
None

See Also:
iMultiplay.ClientOptionsServerAIBotsSkill


iMultiplay.ClientOptionsSetServerArcadeMode

Change the Arcade Mode setting in the multiplayer options.

prototype iMultiplay.ClientOptionsSetServerArcadeMode( bool arcade );

Parameters:
arcade : TRUE for arcade mode, FALSE otherwise.

Return Value:
None

See Also:
iMultiplay.ClientOptionsServerArcadeMode


iMultiplay.ClientOptionsSetServerFragLimit

Set the server frag limit in the multiplayer options.

prototype iMultiplay.ClientOptionsSetServerFragLimit( int limit );

Parameters:
limit : The limit to set.

Return Value:
None

See Also:
iMultiplay.ClientOptionsServerFragLimit


iMultiplay.ClientOptionsSetServerMap

Set the server map in the multiplayer options.

prototype iMultiplay.ClientOptionsSetServerMap( string map );

Parameters:
map : The map to set.

Return Value:
None

See Also:
iMultiplay.ClientOptionsServerMap


iMultiplay.ClientOptionsSetServerName

Set the server name in the multiplayer options.

prototype iMultiplay.ClientOptionsSetServerName( string name );

Parameters:
name : The name to set.

Return Value:
None

See Also:
iMultiplay.ClientOptionsServerName


iMultiplay.ClientOptionsSetServerPackage

Set the server Pog package in the multiplayer options.

prototype iMultiplay.ClientOptionsSetServerPackage( string package );

Parameters:
name : The package to set.

Return Value:
None

See Also:
iMultiplay.ClientOptionsServerPackage


iMultiplay.ClientOptionsSetServerTimeLimit

Set the server frag limit in the multiplayer options.

prototype iMultiplay.ClientOptionsSetServerTimeLimit( int limit );

Parameters:
limit : The limit to set.

Return Value:
None

See Also:
iMultiplay.ClientOptionsServerTimeLimit


iMultiplay.ClientOptionsSetShip

Set the client's ship type in the multiplayer options.

prototype iMultiplay.ClientOptionsSetShip( string ship_url );

Parameters:
ship_url : The URL of the ship.

Return Value:
None

See Also:
iMultiplay.ClientOptionsShip


iMultiplay.ClientOptionsShip

Return the client's ship, as set in the multiplayer options.

prototype string iMultiplay.ClientOptionsShip();

Parameters:
None.

Return Value:
The resource URL of the client's ship as set in the options.

See Also:
iMultiplay.ClientOptionsSetShip


iMultiplay.ClientRequestedToCycle

Check if map cycling is enabled.

prototype bool iMultiplay.ClientRequestedToCycle();

Parameters:
None

Return Value:
TRUE for map cycling on, FALSE otherwise.

See Also:
iMultiplay.ClientSetRequestedToCycle


iMultiplay.ClientSetRequestedToCycle

Set map cycling on or off.

prototype iMultiplay.ClientSetRequestedToCycle( bool cycle );

Parameters:
cycle : TRUE to cycle, FALSE otherwise.

Return Value:
None.

See also:
iMultiplay.ClientRequestedToCycle


iObjectives

This package allows the adding, removing and status manipulation of game objectives.

Type definitions:

  • eObjectivesState

Functions:

  • Add
  • Remove
  • SetState

Notes:

Objectives are cleared when the ship enters the player base, and so scripts which use objectives must manually restore them when the player launches from the base.


iObjectives.eObjectiveState

This enumeration is used for the different objective states.

enum eObjectiveState
{
    // Objective has been supplied but not completed
    OS_Incomplete,

    // Objective has been completed successfully
    OS_Succeeded,

    // Objective has been failed
    OS_Failed
};

Notes:
The declaration of this enumeration can be found in iObjectives.h.


iObjectives.Add

Add an objective to the player's list. Pass the localised text key which identifies the objective.

prototype iObjectives.Add( string key );

Parameters:
key : The text key of the objective.

 Return value:
None.

Notes:
New objectives have the default status OS_Incomplete.

See also:
iObjectives.Remove, iObjectives.SetState


iObjectives.Remove

Silently remove an objective from the player's list. Pass the key to identify the objective.

prototype iObjectives.Remove( string key );

Parameters:
key : The text key of the objective.

 Return value:
None.

Notes:
Normally SetState should be used to handle objective changes, however this command is useful when an objective is no longer required.

See also:
iObjectives.Add, iObjectives.SetState


iObjectives.SetState

Change the state of an objective which already exists. Pass the key to identify the objective and the new state.

prototype iObjectives.SetState( string key, eObjectiveState state );

Parameters:
key : The text key of the objective.
 state : The new state of the objective.

 Return value:
None.

See also:
iObjectives.eObjectiveState, iObjective.Add, iObjectives.Remove


iScore

The iScore package is used to log scores, display them, and manipulate the scoring system.

Functions:

Logging

These functions deal with logging of scores.

  • AddKill
  • DisableLogging
  • EnableLogging
  • GotoRestartPoint
  • SetRestartPoint

Piracy

These functions deal with piracy ( cargo pod stealing ) scores.

  • AddPiracy
  • PodPiracyCount
  • PodPiracyValue

Setup

These functions deal with setting up scores.

  • AddSkillRating
  • SetKillValue

Displaying Scores

These functions deal with displaying scores.

  • HTMLisedStats
  • Total


iScore.AddKill

Credits the player ship with a kill of the given vessel.

prototype iScore.AddKill( hship ship, hisim vessel );

Parameters:
ship : The player ship
vessel : The vessel to credit the kill for.

Return value:
None.

See also:
iScore.SetKillValue


iScore.DisableLogging

Disable score logging.

prototype iScore.DisableLogging();

Parameters:
None.

Return value:
None.

See Also:
iScore.EnableLogging


iScore.EnableLogging

Enable score logging.

prototype iScore.EnableLogging();

Parameters:
None.

Return value:
None.

See Also:
iScore.DisableLogging


iScore.GotoRestartPoint

Reset the 'since launch' scores to those recorded at the restart point.

prototype iScore.GotoRestartPoint();

Parameters:
None.

Return value:
None.

See Also:
iScore.SetRestartPoint


iScore.SetRestartPoint

Record the 'since launch' scores.

prototype iScore.SetRestartPoint();

Parameters:
None.

Return value:
None.

See Also:
iScore.GotoRestartPoint


iScore.AddPiracy

Adds the given cargo type in the given quantity to the current score rating. This will compute the value of the goods automatically.

prototype iScore.AddPiracy( int cargo_type, int quantity );

Parameters:
cargo_type : The cargo type.
quantity : The quantity 'liberated'.

Return value:
None.


iScore.PodPiracyValue

Returns the overall value (current flight and aggregate) of pirated pods.

prototype int iScore.PodPiracyValue();

Parameters:
None

Return value:
The total value of pirated pods.

See Also:
iScore.PodPiracyCount


iScore.PodPiracyCount

Returns the overall number of pods pirated (current flight and aggregate).

prototype int iScore.PodPiracyCount();

Parameters:
None

Return value:
The total number of pirated pods.

See Also:
iScore.PodPiracyValue


iScore.AddSkillRating

Sets the title for the given minimum score.

prototype iScore.AddSkillRating( int value, string rating, );

Parameters:
value : The score for destroying the ship.
rating : The rating string key.

Return value:
None.

See also:
iScore.SetSkillValue


iScore.SetKillValue

Sets the score given for killing the given ship type. This must be a valid member of the valued ship types.

prototype iScore.SetKillValue( string ship_type, int value );

Parameters:
ship_type : The type of ship, e.g. T_Tug
value : The score for destroying the ship.

Return value:
None.

Notes:
See the iSim package for details of valid ship types.

See also:
iScore.AddSkillRating


iScore.HTMLisedStats

Get a HTML version of the statistics.

prototype string iScore.HTMLisedStats();

Parameters:
None

Return value:
The stats as a HTML string.

See Also:
iScore.Total


iScore.Total

Returns the total score obtained (current flight and aggregate).

prototype int iScore.Total();

Parameters:
None

Return value:
The total score.


iCargo

This package governs the creation of cargo types and manipulation of their properties.

Type definitions:

  • hcargo
  • eCargoType
  • eCargoPodType

Functions:

  • Cast
  • CanManufacture
  • CanRecycle
  • Create
  • EncyclopediaEntry
  • Find
  • ManufactureValue
  • MarkInsignificant
  • Name
  • PlayerKnowsAbout
  • PlayerSystem
  • RecycleValue
  • SetCanRecycle
  • SetManufactureValue
  • SetPlayerKnowsAbout
  • SetRecycleValue
  • SetValue
  • ShipSystemTemplate
  • Significant
  • Value

Notes:

This package deals exclusively with types of cargo, and not the creation of individual cargo pods.


iCargo.hcargo

A handle to a cargo object.

hobject : hcargo;


iCargo.eCargoType Enumerations

These enumerations define all the cargo types available.
CT_Invalid
CT_WasteBlocks
CT_PlasticWaste
CT_OrganicPulp
CT_WastePaper
CT_DiseasedSewage
CT_FrozenSewage
CT_RawSewage
CT_SugarCane
CT_Fish
CT_Fruit
CT_Grain
CT_Meat
CT_Potatoes
CT_Rice
CT_Soya
CT_Vegetables
CT_EdibleFungi
CT_FoodBlocks
CT_FoodPills
CT_MealInABar
CT_PseudoShake
CT_RecoveredMeat
CT_SyntheticCheese
CT_SyntheticProtein
CT_SurvivalRations
CT_DrinkingWater
CT_Apes
CT_Birds
CT_DonorPigs
CT_DrugLeeches
CT_Giraffes
CT_Horses
CT_Lions
CT_Weasels
CT_Yaks
CT_Zebras
CT_AttackDogs
CT_BiomassProcessingWorms
CT_Camels
CT_CancerMice
CT_Chickens
CT_Cows
CT_Dogs
CT_EngineeredInsects
CT_Goats
CT_Insects
CT_Pigs
CT_Rodents
CT_Primates
CT_HYL
CT_Foetuses
CT_CloneBoneTissue
CT_CloneEyes
CT_CloneGlands
CT_CloneHearts
CT_CloneIntestines
CT_CloneKidneys
CT_CloneLimbs
CT_CloneLivers
CT_CloneLungs
CT_CloneSkin
CT_VatGrownMuscle
CT_BlankTissueCulture
CT_CommonStrandMaterial
CT_DNAChangers
CT_DNASequencers
CT_DNATattoos
CT_GeneticMarkerAgents
CT_GeneticRejuvinations
CT_TransplantEyes
CT_TransplantGlands
CT_TransplantHearts
CT_TransplantIntestine
CT_TransplantKidneys
CT_TransplantLivers
CT_TransplantLungs
CT_TransplantSkin
CT_Houseplants
CT_PotPlants
CT_Seedlings
CT_Seeds
CT_Algae
CT_PlantPulp
CT_Woodpulp
CT_Trees
CT_SlimeMould
CT_Yeast
CT_NitroBacteria
CT_SoilBacteria
CT_TerraformingBacteria
CT_RecyclingBacteria
CT_AnimalFeed
CT_Compost
CT_Fertiliser
CT_Soil
CT_SportingBodyArmour
CT_Footballs
CT_GolfSupplies
CT_NullBox
CT_PaintGuns
CT_Scuba
CT_TennisEquipment
CT_SportsClothes
CT_ZeroGGymnasia
CT_SportingWeapons
CT_Antiques
CT_Paintings
CT_Sculpture
CT_Caviar
CT_Chocolate
CT_Lobster
CT_RealCoffee
CT_RealMeat
CT_RealTea
CT_Shellfish
CT_Milk
CT_Spices
CT_Game
CT_Cigarettes
CT_Cigars
CT_LeafTobacco
CT_Aphrodisiacs
CT_Caffeine
CT_PhysicalEnhancers
CT_ErzatzCoffee
CT_Euphorics
CT_Halluciogenics
CT_MemoryEnhancers
CT_MoodEnhancers
CT_MoodStabilsers
CT_Stimulants
CT_Tranquilisers
CT_Spirits
CT_Wine
CT_Champagne
CT_Scotch
CT_RealBeer
CT_ZeroBrew
CT_Fur
CT_FurCoats
CT_Vatfur
CT_GoldJewellery
CT_ValuableJewellery
CT_SmartJewels
CT_Watches
CT_Books
CT_Cosmetics
CT_DesignerClothes
CT_MusicalInstruments
CT_Perfume
CT_Toys
CT_NaturalFibreClothing
CT_LuxuryFurniture
CT_CorporateData
CT_XenoData
CT_ResearchData
CT_PersonalData
CT_Mail
CT_ConfidentialData
CT_GovernmentData
CT_PoliceData
CT_MilitaryIntelligence
CT_SecretData
CT_SeekerMineBlueprints
CT_GnatBlueprint
CT_HarrowerBlueprint
CT_HammerBlueprint
CT_SeekerBlueprint
CT_LDSiShortBlueprints
CT_AssaultCannonAmmoBlueprints
CT_TurretFighterBlueprints
CT_RemoteFighterBlueprints
CT_FlareBlueprints
CT_AchillesBlueprints
CT_AntimatterMineBlueprints
CT_AntimatterMissileBlueprints
CT_BlizzardMissileBlueprints
CT_DeadshotBlueprints
CT_DeathblowBlueprints
CT_DecoyBlueprints
CT_DisruptorBlueprints
CT_LDSi3000Blueprints
CT_LDSiMineBlueprints
CT_LDSiMissileBlueprints
CT_SniperCannonAmmoBlueprints
CT_MiningChargeBlueprints
CT_ProximityMineBlueprints
CT_PulsarBlueprints
CT_RemoteMissileBlueprints
CT_RemoteProbeBlueprints
CT_SmartDecoyBlueprints
CT_Autopilots
CT_MatchVelocityAutopilot
CT_StealthProgram
CT_SelfDefenceSoftware
CT_EngineManagementProgram
CT_OcclusionMonitoringSoftware
CT_MilitaryTrackingProgram
CT_MissileAI
CT_UtilitySoftware
CT_ComputerGames
CT_NewsVids
CT_EntertainmentVids
CT_InteractiveText
CT_MusicRecordings
CT_CorporatePropaganda
CT_CapsuleDriveGenerators
CT_LDSClass1Drive
CT_PowerPlant
CT_ShipsDrive
CT_ManoeuvreThrusters
CT_AlphaHeatSink
CT_BetaHeatSink
CT_ColdGasThrusters
CT_MilitaryJumpCapacitor
CT_LDSClass2Drive
CT_LDSClass3Drive
CT_SealedHeatSink
CT_CapsuleDrive
CT_ImprovedManoeuverThrusters
CT_PursuitDrivers
CT_InterceptorDrivers
CT_GammaHeatSink
CT_DeltaHeatSink
CT_AdvancedHeatSink
CT_OmegaHeatSink
CT_HeatSinkSupercooler
CT_ActiveCooler
CT_EmergencyCoolingPod
CT_AntimatterPowerPod
CT_HighYieldFusionInjector
CT_SNRVReloadPod
CT_Thrusterpods
CT_DockOnAutoTurret
CT_SecondaryRing
CT_CapsuleDriveParts
CT_LDSCarrierFields
CT_LDSFieldGenerators
CT_LDSFieldNodes
CT_LDSGeneratorParts
CT_ShipInstruments
CT_ShipSystems
CT_AISystems
CT_CompParts
CT_ShipCPUGradeI
CT_ShipCPUGradeII
CT_ShipCPUGradeIII
CT_ShipCPUGradeIV
CT_ShipCPUGradeV
CT_CompactShipAI
CT_ShipMemoryModule
CT_CPUCores
CT_CPUParts
CT_AudioEquipment
CT_AudioVisualEquipment
CT_DataConsoles
CT_DataScreens
CT_PersonalCommunicators
CT_BodyComps
CT_HandheldScientificInstruments
CT_DataCards
CT_DataChips
CT_DataModules
CT_MemoryModules
CT_NanoAssemblers
CT_NanoFactories
CT_NanoProgrammers
CT_NanoSurgeons
CT_NeuroConnectors
CT_PreprogrammedNanotech
CT_TerraformingNanotech
CT_GeneWriters
CT_CryogenicTanks
CT_Medkits
CT_OrganMatrices
CT_RemoteTables
CT_Autodocs
CT_Autosurgs
CT_HKCounters
CT_MolecularImagers
CT_NanosurgeryEquipment
CT_NMRs
CT_SurgeryKits
CT_CyberEyes
CT_CyberLimbs
CT_CyberneticJackPlugs
CT_CyberneticOrgans
CT_RoboticArms
CT_RoboticChassis
CT_RoboticCPUs
CT_RoboticSensors
CT_DomesticRobots
CT_ConstructionRobots
CT_SecurityRobots
CT_AstronomicalInstruments
CT_ShortRangeActiveSensors
CT_ShortrangePassiveSensors
CT_UCPScanner
CT_PassiveSensorPackage
CT_IFFBeacon
CT_ActiveSensorPackage
CT_AdvancedActiveSensors
CT_AdvancedPassiveSensors
CT_MilitaryGradeActiveSensors
CT_MilitaryGradePassiveSensors
CT_LongRangePassiveSensors
CT_LongRangeActiveSensors
CT_SensorDisruptor
CT_HighPowerSensorDisruptor
CT_AdvancedSensorDisruptor
CT_MarauderCommsScrambler
CT_HyperspaceTracker
CT_LaserDetectors
CT_MonitoringDevices
CT_BricABrac
CT_OfficeSupplies
CT_ReligiousMaterial
CT_Clothing
CT_DisposableClothing
CT_HandTools
CT_Uniforms
CT_Furniture
CT_CleaningProducts
CT_HygieneGoods
CT_HumanitarianAid
CT_WoundDressings
CT_Anaesthetics
CT_Antibiotics
CT_Antiseptics
CT_Immunosuppressives
CT_MedicalDrugs
CT_Vaccines
CT_AntiAgingTreatments
CT_RejuvenationTratments
CT_PainKillers
CT_EmergencySpaceSuits
CT_PersonalGasJets
CT_SpaceSuits
CT_SuitPatches
CT_SurvivalBubbles
CT_SurvivalPacks
CT_SurvivalCloaks
CT_EmergencyHeaters
CT_FieldGenerators
CT_ReactorParts
CT_ReactorSpares
CT_ReactorTargets
CT_FissionGenerators
CT_FusionGenerators
CT_Batteries
CT_SolarPanels
CT_Solettas
CT_AtmosphericScrubbers
CT_PlanetHeaters
CT_CFCGenerators
CT_HydroponicsEquipment
CT_Biovators
CT_AgriHarvestors
CT_Tractors
CT_TractorParts
CT_Aerodynes
CT_Aircars
CT_Dirigibles
CT_GroundCars
CT_ConstructionVehicles
CT_Hovercars
CT_Hovercraft
CT_Rotorcraft
CT_Trucks
CT_LasTanks
CT_Lathes
CT_MicroengineeringTools
CT_Drillers
CT_HabitationPods
CT_HousingModules
CT_LifeSupportSystems
CT_StationComponents
CT_PrefabricatedStationModules
CT_StationConnectors
CT_PrefabricatedHousing
CT_Recyclers
CT_VaccumeDomes
CT_ArmourPatches
CT_ArmourPlates
CT_Hullplates
CT_HullRepairKits
CT_Conduits
CT_FloorGrids
CT_GravGrids
CT_Wiring
CT_EarthMovers
CT_HandDrills
CT_LaserDrills
CT_MiningDisplacers
CT_MiningDrones
CT_VehicleDrills
CT_Rubble
CT_Aggregates
CT_RockDust
CT_Sand
CT_NeutroniumOre
CT_GoldOre
CT_CommonOre
CT_SilverOre
CT_PlatinumOre
CT_RadioactiveOre
CT_UnprocessedGas
CT_Air
CT_Helium3
CT_BlockIce
CT_CrushedIce
CT_DirtyIce
CT_DeionisedWater
CT_Carbon
CT_Nitrates
CT_Oxygen
CT_Phosphates
CT_Sulphur
CT_Alkalines
CT_Sodium
CT_Phosphides
CT_Sulfides
CT_Tellurides
CT_InorganicAcids
CT_Intermetallics
CT_BattleScrap
CT_CompactedScrapMetal
CT_MisCasts
CT_ScrapMetal
CT_Gold
CT_Platinum
CT_Silver
CT_MetalBars
CT_MetalBillets
CT_MetalRods
CT_Wire
CT_Rivets
CT_RadioactiveWaste
CT_Uranium
CT_Plutonium
CT_FissionInitiators
CT_Neutronium
CT_ExoticMetals
CT_RareMetals
CT_FeedStock
CT_PressurisedHydrocarbonGas
CT_Oil
CT_Petroleum
CT_PlasticBars
CT_PlasticBlocks
CT_PlasticCables
CT_PlasticGel
CT_PlasticPellets
CT_LiquifiedFuel
CT_LiquifiedFusionPremix
CT_BoosterAgent
CT_FuelPellets
CT_FuelRods
CT_FloorPlates
CT_Girders
CT_WallPlates
CT_BeanstalkWire
CT_FoamMetal
CT_MacroCrystallineMetals
CT_Monowire
CT_HeavyGirders
CT_CutGemstones
CT_IndustrialGemstones
CT_UncutGemstones
CT_AntimatterContainers
CT_Antimatter
CT_AntimatterPods
CT_APCs
CT_TurretFighter
CT_RemoteFighter
CT_ArtilleryFVs
CT_FireSupportFVs
CT_GravTanks
CT_HoverTanks
CT_Tanks
CT_TankParts
CT_AntimatterFuses
CT_TwinPackMissileLauncher
CT_LDSiShortMissiles
CT_LDSiShortMissile
CT_Flares
CT_Flare
CT_SeekerMissiles
CT_SeekerMissile
CT_HarrowerMissiles
CT_HarrowerMissile
CT_GnatRockets
CT_GnatRocket
CT_HammerRockets
CT_HammerRocket
CT_LDSiMissiles
CT_LDSiMissile
CT_MiningCharges
CT_MiningCharge
CT_TripackMissileLauncher
CT_BlizzardRocketPod
CT_BlizzardRocket
CT_RemoteProbes
CT_RemoteProbe
CT_RemoteMissiles
CT_RemoteMissile
CT_DeadshotMissiles
CT_DeadshotMissile
CT_LDSi3000Missiles
CT_LDSi3000Missile
CT_QuadpackMissileLauncher
CT_DeathblowRemote
CT_DeathblowRemoteMissile
CT_AntimatterRemote
CT_AntimatterRemoteMissile
CT_InternalMissileMagazine
CT_DisruptorMissiles
CT_DisruptorMissile
CT_SmartDecoy
CT_SmartDecoyCountermeasure
CT_Decoys
CT_Decoy
CT_PulsarDisruptors
CT_PulsarDisruptor
CT_HullMissileHardPoint
CT_AchillesShieldDisruptors
CT_AchillesShieldDisruptor
CT_ProximityMines
CT_ProximityMine
CT_AntimatterMines
CT_AntimatterMine
CT_LDSIMines
CT_LDSIMine
CT_SeekerMines
CT_SeekerMine
CT_LDSIWarheads
CT_MissileParts
CT_MissileThrusters
CT_MissileWarheads
CT_CombatPowersuits
CT_SidearmClips
CT_BattlePacks
CT_Explosives
CT_Grenades
CT_HandWeapons
CT_ManpackMissiles
CT_BiologicalWeaponsAgents
CT_ChemicalWeaponsAgents
CT_NeutronWarheads
CT_DirtyFissionWarheads
CT_HostileTerraformingAgents
CT_NanotechWeapons
CT_AcceleratorRings
CT_NeutronBeamCannon
CT_WeaponLinkHardware
CT_CommunicationsLaser
CT_TrackingComputer
CT_ParticleBeamCannon
CT_MiningLasers
CT_AssaultCannon
CT_AssaultCannonAmmo
CT_AssaultCannonAmmoRound
CT_LightPBC
CT_CooledPBC
CT_RapidFirePBC
CT_LongRangeCannon
CT_CuttingBeam
CT_WideanglePBC
CT_EnhancedAimPBC
CT_QuadLightPBC
CT_HeavyBeamCannon
CT_LongRangeCannonAmmo
CT_LongRangeCannonAmmoRound
CT_TargetedPBC
CT_AssaultCannonRingModel
CT_PulseAcceleratedPBC
CT_AntimatterParticleBeam
CT_AntimatterStreamer
CT_Accumulators
CT_PointDefenceTurret
CT_FireControlSensors
CT_PBCAccelerators
CT_PlasmaStorageRings
CT_GatlingPBCs
CT_HeavyPBCs
CT_LightPBCs
CT_PBCs
CT_MeteorShield
CT_Level1AutorepairSystem
CT_DefenceShield
CT_Level2AutorepairSystem
CT_RepairControlProgram
CT_LightDefenceShield
CT_InstantShieldControl
CT_ReactorHardening
CT_ArmouredHullPlates
CT_Level3Autorepairsystem
CT_LowSignatureHullplates
CT_MilitaryShields
CT_ShieldSynchroniser
CT_Level4Autorepairsystem
CT_CombatShields
CT_MilitaryAggressorShields
CT_AggressorShieldUpgrade
CT_MinersShield
CT_Level5Autorepairsystem
CT_ParticleScreenShieldUpgrade
CT_AssaultShield
CT_PowerPlantAutorepair
CT_ShieldBooster
CT_AdvancedHullMaterialRefit

Notes:
The declaration of this enumeration can be found in CargoTypes.h.


iCargo.eCargoPodType Enumerations

These enumerations define the cargo pod types available.
enum eCargoPodType
{
    PT_MiniPod,	// Mini Pod ( No longer used )
    PT_MaxiPod 	// Normal Cargo pod.
};

Notes:
Minipods are no longer used in the game, so this enumeration is redundant.
The declaration of this enumeration can be found in CargoTypes.h.


iCargo.Cast

Cast a handle up to a handle to cargo object.

prototype hcargo iCargo.Cast( hobject handle );

Parameters:
handle : The handle to cast.

Return value:
A handle to a cargo object..

Notes:
If the object handle is invalid or the object is not a cargo object then a null handle is returned.


iCargo.CanManufacture

Find out if the player can manufacture a certain cargo type.

prototype bool iCargo.CanManufacture( hcargo cargo );

Parameters:
cargo : The cargo type.

Return value:
TRUE if the player can manufacture the cargo type, FALSE otherwise.

See Also:
iCargo.SetCanManufacture, iCargo.ManufactureValue, iCargo.SetManufactureValue


iCargo.CanRecycle

Find out if the player can recycle a certain cargo type.

prototype bool iCargo.CanRecycle( hcargo cargo );

Parameters:
cargo : The cargo type.

Return value:
TRUE if the player can recycle the cargo type, FALSE otherwise.

See Also:
iCargo.RecycleValue, iCargo.SetRecycleValue, iCargo.SetCanRecycle


iCargo.Create

Create a new type of cargo. Only one cargo may be defined for each value of 'type' - extra definitions are ignored.

The cargo object is automatically stored in an internal cargo registry so no handle is returned. It is normally only necessary to use the type numbers when referring to cargo types.

prototype iCargo.Create( int type,
             string name_key,
             bool player_knows_about,
             int value,
             bool can_manufacture,
             int manufacture_value,
             bool can_recycle,
             int recycle_value,
             string ship_system_template,
             string encyclopedia_entry,
             bool player_system );

Parameters:
type : The type number of the cargo.
name_key : The string name key for the cargo type.
player_knows_about : Boolean specifying if the player knows about that cargo type.
value : The value of the cargo.
can_manufacture : Specifies if the cargo can be manufactured by the player.
manufacture_value : How much it costs to manufacture (in resource units).
can_recycle : Specifies if the cargo is recyclable.
recycle_value : How many resource units you get when the cargo is recycled.
ship_system_template : If the cargo is a ship's system, this string specifies the resource template of the system.
encyclopedia_entry : The resource URL of the cargo's encyclopedia entry.
player_system : Specifies if the cargo is a system that can be placed on a player ship.

Return value:
None

See Also:
eCargoType


iCargo.EncyclopediaEntry

Return the cargo's encyclopedia entry url.

prototype string iCargo.EncyclopediaEntry( hcargo cargo );

Parameters:
cargo : The cargo type.

Return value:
A string containing the encyclopedia url.


iCargo.Find

Find a type of cargo from its index (it must already have been created) and return its handle. If the cargo doesn't exist the return value is none.

prototype hcargo iCargo.Find( int type );

Parameters:
type : The cargo type to find.

Return value:
A handle to a cargo object, or none if the cargo isn't found.


iCargo.ManufactureValue

Return the cargo's manufacture value.

prototype int iCargo.ManufactureValue( hcargo cargo );

Parameters:
cargo : The cargo type.

Return value:
An int containing the cargo manufacture value.

See Also:
iCargo.CanManufacture, iCargo.SetCanManufacture, iCargo.SetManufactureValue


iCargo.MarkInsignificant

Mark a cargo type as being insignificant, i.e. not worth showing to the player.

prototype iCargo.MarkInsignificant( hcargo cargo );

Parameters:
cargo : The cargo type.

Return value:
None

See Also:
iCargo.Significant


iCargo.Name

Return the cargo's name.

prototype string iCargo.Name( hcargo cargo );

Parameters:
cargo : The cargo type to find the name from.

Return value:
A string containing the cargo name.


iCargo.PlayerKnowsAbout

Find out if the player knows about a certain cargo type.

prototype bool iCargo.PlayerKnowsAbout( hcargo cargo );

Parameters:
cargo : The cargo type.

Return value:
TRUE if the player knows about the cargo type, FALSE otherwise.

See Also:
iCargo.SetPlayerKnowsAbout


iCargo.PlayerSystem

Find out if the cargo type represents a player ship system.

prototype bool iCargo.PlayerSystem( hcargo cargo );

Parameters:
cargo : The cargo type.

Return value:
TRUE if the cargo types represents a player ship system, FALSE otherwise.


iCargo.RecycleValue

Return the cargo's recycle value.

prototype int iCargo.RecycleValue( hcargo cargo );

Parameters:
cargo : The cargo type.

Return value:
An int containing the cargo recycle value.

See Also:
iCargo.SetRecycleValue, iCargo.CanRecycle, iCargo.SetCanRecycle


iCargo.SetCanManufacture

Set a cargo type as manufacturable by the player.

prototype iCargo.SetCanManufacture( hcargo cargo, bool can_manufacture );

Parameters:
cargo : The cargo type.
can_manufacture : TRUE to set the cargo as manufacturable.

Return value:
None

See Also:
iCargo.CanManufacture, iCargo.ManufactureValue, iCargo.SetManufactureValue


iCargo.SetCanRecycle

Set whether a cargo can be recycled or not.

prototype iCargo.SetCanRecycle( hcargo cargo, bool can_recycle );

Parameters:
cargo : The cargo type.
can_recycle : TRUE to set a cargo recyclable, FALSE otherwise.

Return value:
None

See Also:
iCargo.RecycleValue, iCargo.SetRecycleValue, iCargo.CanRecycle


iCargo.SetManufactureValue

Set a cargo's manufacture value.

prototype iCargo.SetManufactureValue( hcargo cargo, int value );

Parameters:
cargo : The cargo type.
value : The manufacture value to set.

Return value:
None

See Also:
iCargo.CanManufacture, iCargo.SetCanManufacture, iCargo.ManufactureValue


iCargo.SetPlayerKnowsAbout

Set a cargo type as being known by the player.

prototype iCargo.PlayerKnowsAbout( hcargo cargo, bool knows );

Parameters:
cargo : The cargo type.
knows : TRUE to set the cargo as known, FALSE otherwise.

Return value:
None

See Also:
iCargo.PlayerKnowsAbout


iCargo.SetRecycleValue

Set a cargo's recycle value.

prototype iCargo.SetRecycleValue( hcargo cargo, int value );

Parameters:
cargo : The cargo type.
value : The recycle value to set.

Return value:
None

See Also:
iCargo.RecycleValue, iCargo.CanRecycle, iCargo.SetCanRecycle


iCargo.SetValue

Set a cargo's value.

prototype iCargo.SetValue( hcargo cargo, int value );

Parameters:
cargo : The cargo type.
value : The cargo value.

Return value:
None

See Also:
 iCargo.Value


iCargo.ShipSystemTemplate

Return the cargo's ship system template (if available).

prototype string iCargo.ShipSystemTemplate( hcargo cargo );

Parameters:
cargo : The cargo type to find the name from.

Return value:
A string containing the ship system template.

Notes:
Not all cargo items represent ship systems. Use iCargo.PlayerSystem to find out if a cargo type represents a ship system.


iCargo.Significant

Check if a cargo type is significant.

prototype bool iCargo.Significant( hcargo cargo );

Parameters:
cargo : The cargo type.

Return value:
TRUE if the cargo is significant, FALSE otherwise.

See Also:
iCargo.MarkInsignificant


iCargo.Value

Return the cargo's value.

prototype int iCargo.Value( hcargo cargo );

Parameters:
cargo : The cargo type.

Return value:
An int containing the cargo value.

See Also:
iCargo.SetValue


iEmail

This package governs the player's email store and allows a scripter to send messages to the player.

Type definitions:

  • hemail

Functions:

  • ArchiveSize
  • Body
  • Cast
  • Find
  • FillArchivedEmailListBox
  • ID
  • InboxSize
  • MarkAsRead
  • NthInArchive
  • NthInInbox
  • Read
  • Received
  • ResetWindows
  • SendEmail
  • Sender
  • ShuntReadEmailToArchive
  • Subject
  • Unread
  • Urgent

Notes:

The email package governs the player's email store. Function here allow a scripter to send the player emails and to query the email store.

The store consists of two sections - the inbox, where new and still relevant emails are stored, and the archive, where email are moved to when they become irrelevant.


hemail

A handle to a game email.

hemail : hobject;

Notes:
Emails are given an email ID when they are sent. This ID is unique and is used both to identify emails and to order them by time of sending.


iEmail.ArchiveSize

Get the number of emails in the archive.

prototype int iEmail.ArchiveSize();

Parameters:
None.

Return value:
The number of emails in the archive.

See also:
iEmail.NthInArchive, iEmail.InboxSize, iEmail.Unread


iEmail.Body

Get the resource containing the body of a given email.

prototype string iEmail.Body( hemail email );

Parameters:
email : The email to query.

Return value:
The resource containing the body of the given email.


iEmail.Cast

Attempt to cast a handle up to a handle to an email.

prototype hemail iEmail.Cast( hobject object );

Parameters:
object : The object to cast.

Return value:
A handle to an email, or a null handle if the object is not a valid email.

Notes:
It is valid to use this function to check a handle to see if it is an email object.


iEmail.FillArchivedEmailListBox

Fill the given list box with windows describing archived emails

prototype iEmail.FillArchivedEmailListBox( hwindow list_box );

Parameters:
list_box : The list box to fill with email windows.

Return value:
None

Notes:
This function requires a GUI List Box window to be defined first.


iEmail.Find

Attempt to find the given email in the player's email store.

prototype hemail iEmail.Find( string email_body_request );

Parameters:
email_body_reuqest : The email ini file resource request.

Return value:
A handle to the email, or none if the email isn't found.


iEmail.ID

Get the email ID of the given email.

prototype int iEmail.ID( hemail email );

Parameters:
email : The email to query.

Return value:
The unique email ID of the given email.


iEmail.InboxSize

Get the number of emails in the inbox.

prototype int iEmail.InboxSize();

Parameters:
None.

Return value:
The number of emails in the inbox.

See also:
iEmail.NthInInbox, iEmail.ArchiveSize.


iEmail.MarkAsRead

Mark the given email as read.

prototype iEmail.MarkAsRead( hemail email );

Parameters:
email : The email to alter.

Return value:
None.


iEmail.NthInArchive

Get the nth entry in the archive.

prototype hemail iEmail.NthInArchive( int n );

Parameters:
n : The index into the archive to get.

Return value:
The email at index n in the archive.

Notes:
If there is not an nth entry in the archive then a null handle is returned.

See also:
iEmail.ArchiveSize, iEmail.NthInInbox, iEmail.Unread


iEmail.NthInInbox

Get the nth entry in the inbox.

prototype hemail iEmail.NthInInbox( int n );

Parameters:
n : The index into the inbox to get.

Return value:
The email at index n in the inbox.

Notes:
If there is not an nth entry in the inbox then a null handle is returned.

See also:
iEmail.InboxSize, iEmail.NthInArchive.


iEmail.Read

Has the given email been read?

prototype bool iEmail.Read( hemail email );

Parameters:
email : The email to query.

Return value:
True if the given email has been read.


iEmail.Received

Determines whether or not the player has received the email identifed by the given email ini file resource request.

prototype bool iEmail.Received( string email_ini );

Parameters:
email_ini : The email ini file resource request.

Return value:
Whether or not the given email has been received by the player.


iEmail.ResetWindows

Pull the email windows out of their existing window manager and back into the email store

prototype iEmail.ResetWindows();

Parameters:
None

Return value:
None


iEmail.SendEmail

Send an email to the player.

prototype iEmail.SendEmail( string sender,
                string subject,
                string email_body_request,
                bool urgent );

Parameters:
sender : A text key for the sender name.
subject : A text key for the subject.
email_body_request : An INI file for an emai html file.
urgent : TRUE for an urgent email ( marked with an asterisk ), FALSE otherwise.

Return value:
None.

Notes:
The email INI is an initialisation file which contains the email subject, sender and the HTML resource for the body of the email.

The email will appear instantly in the player's inbox.


iEmail.Sender

Get the sender of a given email.

prototype string iEmail.Sender( hemail email );

Parameters:
email : The email to query.

Return value:
The sender of the given email.


iEmail.ShuntReadEmailToArchive

Move all read email in the inbox to the archive.

prototype iEmail.ShuntReadEmailToArchive();

Parameters:
None

Return value:
None


iEmail.Subject

Get the subject of a given email.

prototype string iEmail.Subject( hemail email );

Parameters:
email : The email to query.

Return value:
The subject of the given email.


iEmail.Unread

Get the number of unread emails in the inbox.

prototype int iEmail.Unread();

Parameters:
None

Return value:
The number of unread emails.


iEmail.Urgent

Is the given email urgent?

prototype bool iEmail.Urgent( hemail email );

Parameters:
email : The email to query.

Return value:
True if the given email has been marked as urgent.


iGame

This package collects various functions that deal with miscellaneous game features and settings.

Type definitions:

  • eIGameType
  • eIEarnableMovie

Functions:

General

  • CreateFog
  • DestroyFog
  • EnableBlackOut
  • GameTime
  • GameType
  • GotEarnedMovie
  • MovePlayerBase
  • NextAct
  • PlayMovie
  • PlayMovieLooped
  • RealTime
  • SetGameType
  • SetStartSystem
  • StartNewGame
  • SystemTime

Save Game System

These functions dealing with saving the game. The save game system saves out the following information:
Global Variables, Objectives, Destroyed / Hidden Stations, Hidden Map Locations, States for tasks. It's up to the various game scripts to use the states and global variables to set themselves up as they were when the game was saved.

  • AutosaveSaved
  • LoadGame
  • NameOfSaveInSlot
  • NumberOfSavedGameSlots
  • SaveGame
  • SaveAutosave

Multiplayer

These commands deal with various multiplayer features.

  • JoinNetworkGame
  • Jo inNetworkGameFromLobby
  • SessionName
  • ServerAddress
  • SetSessionName

Notes:

Many of these functions are highly specialised and are intended for use specifically with the standard I-War 2 game content.


iGame.eIGameType

This enumeration is used for the different I-War 2 game types.

enum eIGameType
{
    // Standard game type
    IGT_SinglePlayer,

    // Demo single player game
    IGT_DemoSinglePlayer,

    // Mod game
    IGT_Mod,

    // Multiplayer game
    IGT_MultiPlayer
};

Notes:
The declaration of this enumeration can be found in iGame.h.


iGame.eIEarnableMovie

This enumeration is used for the different I-War 2 earnable movies.

enum eEarnableMovie
{
    EM_ComsecDiscovery,
    EM_BaseDiscovery,
    EM_BaseEntry,
    EM_JailBreak,
    EM_Outro
};

Notes:
The declaration of this enumeration can be found in iGame.h.


iGame.CreateFog

Creates nebula type fog, which fades in over the specified time.

prototype iGame.CreateFog( float fade_in_time );

Parameters:
fade_in_time : The time for the fog to fade in.

 Return value:
None

Notes:
This command is primarily used to create fog effects for multiplayer games.

See also:
iGame.DestroyFog


iGame.DestroyFog

Destroys nebula type fog (previously created with iGame.CreateFog), which fades out over the specified time.

prototype iGame.CreateFog( float fade_out_time );

Parameters:
fade_out_time : The time for the fog to fade out.

Notes:
This command is primarily used to destroy fog effects in multiplayer games.

 Return value:
None

See also:
iGame.CreateFog


iGame.EnableBlackout

Turn screen blanking on / off.

prototype iGame.EnableBlackout( bool enable );

Parameters:
enable : TRUE to blank the screen, FALSE to unblank the screen.

 Return value:
None

Notes:
As scripts don't work instantaneously it's occasionally useful to blank the screen during the times when the game is setting things up. That way you prevent objects popping into view, or other effects which spoil the visual appearance of the game.


iGame.GameTime

Returns the game time in seconds.

prototype float iGame.GameTime();

Parameters:
None.

 Return value:
The game time in seconds.

See also:
iGame.SystemTime, iGame.RealTime


iGame.GameType

Returns the current game type.

prototype eIGameType iGame.GameType();

Parameters:
None.

 Return value:
The game type as an enum.

See also:
eIGameType, iGame.SetGameType


iGame.GotEarnedMovie

Check to see if the player has earned a given movie.

prototype bool iGame.GotEarnedMovie( eEarnableMovie movie );

Parameters:
movie : The movie enum, as defined in eEarnableMovie.

 Return value:
TRUE if the movie has been earned, FALSE otherwise.


iGame.MovePlayerBase

Move the player base. It will be attached to the first waypoint called "player_base_location" in the target system.

prototype iGame.MovePlayerBase( string system_url );

Parameters:
system_url : The url of the solar system map to move the player base to.

 Return value:
None


iGame.NextAct

Move to the next act.

prototype iGame.NextAct( string act_function );

Parameters:
act_function : The function to call when starting a new act.

 Return value:
None

Notes:
The act function string must specify the function name in full, i.e. "iActOne.ActOneStart", and the act function must be exported by the package it which is is contained.

See also:
iGame.StartNewGame


iGame.PlayMovie

Play a movie. This will pause the game while playing.

prototype iGame.PlayMovie( string url );

Parameters:
url : The url of the movie.

 Return value:
None

Notes:
Movie urls do not have use filename prefix or extension, e.g:

iGame.PlayMovie( "/movies/midtro" );

See also:
iGame.PlayMovieLooped


iGame.PlayMovieLooped

Play a movie continously. This will pause the game while playing. The movie will continue playing until quit by the player.

prototype iGame.PlayMovie( string url );

Parameters:
url : The url of the movie.

 Return value:
None

Notes:
Movie urls do not have use filename prefix or extension, e.g:

iGame.PlayMovieLooped( "/movies/midtro" );

See also:
iGame.PlayMovie


iGame.RealTime

Returns the current real time, as defined by the computer's real-time clock.

prototype string iGame.RealTime();

Parameters:
None.

 Return value:
The time as a string.

See also:
iGame.GameTime, iGame.SystemTime


iGame.SetGameType

Set the game type.

prototype iGame.GameType( eIGameType game_type );

Parameters:
game_type : The game type enum, as defined in eIGameType.

 Return value:
None

See also:
eIGameType, iGame.GameType


iGame.SetStartSystem

Change the starting system for the game. The player base will move to the new system and be attached to the first waypoint called "player_base_location"

prototype iGame.SetStartSystem( string system_url );

Parameters:
system_url : The url of the new starting solar system map.

 Return value:
None

See Also:
iGame.StartNewGame


iGame.StartNewGame

Start a new single player game, in the given system, and in the given act number.

prototype iGame.StartNewGame( string system_url, int act );

Parameters:
system_url : The url of the solar system map the player ship starts in.
act : The number of the game's starting act.

 Return value:
None

See also:
iGame.NextAct


iGame.SystemTime

Returns the system time in elapsed milliseconds.

prototype float iGame.SystemTime();

Parameters:
None.

 Return value:
The game time in seconds.

See also:
iGame.GameTime, iGame.RealTime


iGame.AutosaveSaved

Check if an autosave has been performed.

prototype bool iGame.AutosaveSaved();

Parameters:
None

Return value:
TRUE if an autosave has been performed, FALSE otherwise.


iGame.LoadGame

Load a game, using the specified save game name.

prototype iGame.NameOfSaveInSlot( string name );

Parameters:
name : The name of the save game.

Return value:
None

See also:
iGame.SaveGame, iGame.SaveAutosave, iGame.AutosaveSaved, iGame.NumberOfSavedGameSlots, iGame.NameOfSaveInSlot


iGame.NameOfSaveInSlot

Get the name of the saved game in the given slot number. Returns an empty string is that slot is not used.

prototype string iGame.NameOfSaveInSlot( int slot );

Parameters:
slot : The number of the save game slot.

Return value:
The name of the saved game, or an empty string if the slot is unused.

See also:
iGame.LoadGame, iGame.SaveGame, iGame.SaveAutosave, iGame.AutosaveSaved, iGame.NumberOfSavedGameSlots


iGame.NumberOfSavedGameSlots

Get the number of saved game slots,

prototype int iGame.NumberOfSavedGameSlots();

Parameters:
None.

Return value:
The number of saved game slots.


iGame.SaveGame

Save a game in the given slot, with the specified name.

prototype string iGame.SaveGame( int slot, string name );

Parameters:
slot : The number of the save game slot.
name : The name of the save game.

Return value:
None

See also:
iGame.LoadGame, iGame.SaveAutosave, iGame.AutosaveSaved, iGame.NumberOfSavedGameSlots, iGame.NameOfSaveInSlot


iGame.SaveAutosave

Save the current game in the autosave slot

prototype string iGame.SaveAutosave();

Parameters:
None

Return value:
None

See also:
iGame.LoadGame, iGame.SaveGame, iGame.AutosaveSaved, iGame.NumberOfSavedGameSlots, iGame.NameOfSaveInSlot


iGame.JoinNetworkGame

Join the network game with the given session number.

prototype iGame.JoinNetworkGame( int session );

Parameters:
session : The number of the session to join.

 Return value:
None

See also:
iGame.JoinNetworkGameFromLobby


iGame.JoinNetworkGameFromLobby

Join the network game previously set from the lobby.

prototype iGame.JoinNetworkGameFromLobby();

Parameters:
None

 Return value:
None

See also:
iGame.JoinNetworkGame


iGame.SessionName

Returns the multiplayer session name that the game wishes to connect to.

prototype string iGame.SessionName();

Parameters:
None.

 Return value:
The session name as a string.

See Also:
iGame.SetSessionName


iGame.ServerAddress

Returns the IP address of the server that the game wishes to connect to.

prototype string iGame.ServerAddress();

Parameters:
None.

 Return value:
The session IP address as a string.


iGame.SetSessionName

Set the multiplayer session name.

prototype iGame.SetSessionName( string session_name );

Parameters:
session_name : The name of the multiplayer session.

 Return value:
None

See Also:
iGame.SessionName


iHUD

This package allows simple manipulation of various HUD (Head-Up Display) elements.

Type definitions:

  • eAudioCue

Functions:

General

  • FlashElement
  • PlayAudioCue
  • Print
  • SetPrompt
  • SetTarget
  • ShowScore

HUD Menu
These functions query and manipulate the HUD menu.

  • CurrentMenuNode
  • LockMenu
  • SetMenuNodeEnabled


iHUD.eAudioCue

This enumeration is used to play different HUD audio cues.

enum eAudioCue
{
    // Valid input bleep
    AC_ValidInput,

    // Invalid input bleep
    AC_InvalidInput,

    // Target change bleep
    AC_TargetChanged,

    // Missile warning bleep
    AC_MissileWarning,

    // Klaxon
    AC_Klaxon,

    // Ping sound
    AC_SonarPing,

    // How many cues
    eAudioCueCount
};

Notes:
The declaration of this enumeration can be found in iHUD.h.


iHUD.FlashElement

Cause a HUD element to briefly flash on and off. Only one element can flash at a time.

prototype iHUD.FlashElement( string class_name );

Parameters:
class_name : The class name of the HUD element to flash.

 Return value:
None

Notes:
Pass the classname of the element to flash. See flux.ini for possible classnames.


iHUD.PlayAudioCue

Play the given audio cue.

prototype iHUD.PlayAudioCue( eAudioCue cue );

Parameters:
cue : The audio cue to play/

 Return value:
None

See Also:
iHUD.eAudioCue


iHUD.Print

Print a string onto the HUD.

prototype iHUD.Print( string key );

Parameters:
key : The text key to print.

 Return value:
None

Notes:
The string is passed through the normal message log and will be added to the log screen as well as displayed on the HUD.
Be sure to check your message length to make sure it doesn't go off the visible edges of the screen in lower resolution modes, as the message will not word wrap.

See also:
iHUD.SetPrompt


iHUD.SetPrompt

Set both HUD prompt lines.

prototype iHUD.SetPrompt( string first_prompt, string second_prompt );

Parameters:
first_prompt : The first text key to display.
second_prompt : The first text key to display.

Return value:
None

Notes:
 The prompts are not added to the log.
To clear a prompt line, set it to the empty string "".
There is no time-out on prompts - the script must clear them.
Be sure to check your message lengths to make sure they don't go off the visible edges of the screen in lower resolution modes, as the messages will not word wrap.

See also:
iHUD.Print


iHUD.SetTarget

Attempt to the player's current target.

prototype iHUD.SetTarget( hsim sim );

Parameters:
sim : The sim to target.

 Return value:
None

Notes:
If the sim is not in the player's contact list it will not be targeted.


iHUD.ShowScore

Show the player's score screen on the HUD.

prototype iHUD.ShowScore();

Parameters:
 None

 Return value:
None


iHUD.CurrentMenuNode

Return the name (text key) of the current menu node.

prototype string iHUD.CurrentMenuNode();

Parameters:
None

 Return value:
The current HUD menu node as a string.

Notes
See hud.csv for details of the HUD menu node names. The keys all have the form "hud_menu_xxxx".
Screens like the starmap and log screen are also identified in this way.
If the HUD menu is closed the returned string will be empty.

See also:
iHUD.LockMenu, iHUD.SetMenuNodeEnabled


iHUD.LockMenu

Lock the HUD menu to prevent it being operated.

prototype string iHUD.CurrentMenuNode( bool lock );

Parameters:
lock : TRUE to lock, FALSE to unlock.

 Return value:
None

See also:
iHUD.CurrentMenuNode, iHUD.SetMenuNodeEnabled


iHUD.SetMenuNodeEnabled

Sets the enabled/disabled status of a given HUD menu option.

prototype iHUD.SetMenuNodeEnabled( string option, bool enabled );

Parameters:
option : The menu node to enable / disable.
enabled : TRUE to enable, FALSE to disable.

Return value:
None

See also:
iHUD.CurrentMenuNode, iHUD.LockMenu


iInventory

This package provides a means to manipulate and query the contents of the player's inventory. It provides facilities to add and remove inventory items, and enquire the presence or value of those items.

Type definitions:

  • eCargoCategory
  • eCargoSuperSet

Functions:

General

  • Add
  • AddWithoutMarkingNew
  • CancelNewCargoFlags
  • GotBlueprints
  • IsPieceOfAmmo
  • Manufacture
  • ManufactureUnits
  • Recycle
  • Remove
  • SetBluePrintsForCargo
  • TotalWorth

Cargo Types, Categories and Supertypes

These functions deal with Cargo types and their organisation into categories and super sets.

  • CargoCategoryFromName
  • CargoSuperTypeFromName
  • CargoTypeFromCategoryIndex
  • CargoTypeFromName
  • CargoTypeFromSuperTypeIndex
  • CategoryContaining
  • CreateCargoCategory
  • CreateCargoSuperSet
  • NumberOfCargoTypes
  • NumberOfCargoInCategory
  • NumberOfCargoInSuperSet
  • NumberOfRecyclableCargoInCategory
  • NumberOfRecyclableCargoInSuperSet
  • NumTypesInCategory
  • NumTypesInInventory
  • NumTypesInSuperSet
  • QuantityOfNthTypeInCategory
  • QuantityOfNthTypeInInventory
  • QuantityOfNthTypeInSuperSet
  • SuperSetContaining

Inventory Window Functions

These specialised commands deal with the Inventory window, and are used by the Base GUI scripts.

  • FillAddCargoListBox
  • FillInventoryListBox
  • FillRecyclingListBox
  • ResetWindows

Player Ship Functions

These commands allow the adding, removing and querying of the various player ship types.

  • AddCommandSection
  • AddFastAttackShip
  • AddHeavyCorvette
  • AddStormPetrel
  • AddTug
  • GotCommandSection
  • GotFastAttackShip
  • GotHeavyCorvette
  • GotStormPetrel
  • GotTug
  • RemoveCommandSection
  • RemoveFastAttackShip
  • RemoveHeavyCorvette
  • RemoveStormPetrel
  • RemoveTug

Notes:

Potential inventory items are defined by a set of enums: eCargoType.

Super Sets are the top level of cargo categorisation, e.g. CS_OrganicMaterials is a cargo super set.
Categories are the mid level of cargo categorisation, e.g. CC_Fauna is a cargo category that belongs to the above super set.
Cargo types are the lowest level of cargo categorisation, e.g. CT_Weasels is a cargo type that belongs to the above category.


iInventory.eCargoCategory

This enumeration is used to define the various cargo categories.

enum eCargoCategory
{
    // CS_Data
    CC_Blueprints,
    CC_ConsumerData,
    CC_PrivateData,
    CC_SecureData,
    CC_Software,

    // CS_Electronics
    CC_Avionics,
    CC_Computers,
    CC_ConsumerElectronics,
    CC_Cybernetics,
    CC_DataStorage,
    CC_Instrumentation,
    CC_MedicalElectronics,
    CC_Nanotechnology,
    CC_Robotics,

    // CS_HeavyEngineering
    CC_AgriculturalEquipment,
    CC_Environmental,
    CC_MachineTools,
    CC_MiningEquipment,
    CC_PowerSystems,
    CC_Terraforming,
    CC_Vehicles,

    // Luxuries
    CC_Alcohol,
    CC_Art,
    CC_Furs,
    CC_Jewellery,
    CC_LuxuryConsumerGoods,
    CC_LuxuryFoodstuffs,
    CC_Narcotics,
    CC_SportingGoods,

    // CS_ManufacturedGoods
    CC_ConsumerGoods,
    CC_MedicalSupplies,
    CC_Pharmaceuticals,
    CC_SurvivalEquipment,

    // CS_OrganicMaterials
    CC_Bacteria,
    CC_Biomass,
    CC_Fauna,
    CC_Flora,
    CC_Fungi,
    CC_GeneticMaterial,
    CC_ProcessedFoodstuffs,
    CC_UnprocessedFoodstuffs,
    CC_Waste,

    // CS_ProcessedMaterials
    CC_AntimatterGoods,
    CC_ConstructionMaterial,
    CC_Exotics,
    CC_ReactorFuel,
    CC_Gemstones,
    CC_Hydrocarbons,
    CC_CommonMetals,
    CC_Radioactives,

    // CS_RawMaterials
    CC_BulkChemicals,
    CC_Gasses,
    CC_Ore,
    CC_Rocks,
    CC_IndustrialWater,

    // CS_WeaponSystems
    CC_CombatVehicles,
    CC_NBCWarfare,
    CC_Ordinance,
    CC_PersonalWeapons,
    CC_SpacecraftWeapons,
    CC_SpacecraftDefenceSystems
};

Notes:
The declaration of this enumeration can be found in CargoTypes.h.

Notes:
 iCargo.eCargoType, iInventory.eCargoSuperSet


iInventory.eCargoSuperSet

This enumeration is used to define the various cargo super sets. This is the top level categorisation of the commodities.

enum eCargoSuperSet
{
    CS_Data,
    CS_Electronics,
    CS_HeavyEngineering,
    CS_Luxuries,
    CS_ManufacturedGoods,
    CS_OrganicMaterials,
    CS_ProcessedMaterials,
    CS_RawMaterials,
    CS_WeaponSystems
};

Notes:
The declaration of this enumeration can be found in CargoTypes.h.

Notes:
 iCargo.eCargoType, iInventory.eCargoCategory


iInventory.Add

Adds an item or items to the player's inventory.

prototype iInventory.Add( eCargoType item, int quantity );

Parameters:
item : The Enum of the cargo type to add,
quantity : The quantity of that item to add.

Return value:
None.

See also:
iInventory.AddWithoutMarkingNew, iInventory.Remove, iCargo.eCargoType


iInventory.AddWithoutMarkingNew

Adds an item or items to the player's inventory, without marking it as new for the inventory.

prototype iInventory.AddWithoutMarkingNew( eCargoType item, int quantity );

Parameters:
item : The Enum of the cargo type to add,
quantity : The quantity of that item to add.

Return value:
None.

See also:
iInventory.Add, iInventory.Remove, iCargo.eCargoType


iInventory.GotBlueprints

Has the player got the blueprints to manufacture for the given cargo type

prototype bool iInventory.GotBlueprints( eCargoType cargo_type );

Parameters:
cargo_type : The cargo type to check.

Return value:
TRUE if the player has blueprints for the specified cargo type. FALSE otherwise.

See also:
iInventory.SetBlueprintsForCargo, iCargo.eCargoType


iInventory.IsPieceOfAmmo

Find out if a cargo type is a missile or a piece of ammunition.

prototype bool iInventory.KnowsAbout( eCargoType cargo_type );

Parameters:
cargo_type : The enum of the cargo type.

Return value:
TRUE if the cargo type represents a piece of ammunition, FALSE otherwise.

See Also:
iCargo.eCargoType


iInventory.Manfuacture

Manufacture an item using available resource units.

prototype bool iInventory.Manufacture( eCargoType item, int quantity );

Parameters:
item : The enum for the item to manufacture.
quantity : The quantity of that item to manufacture.

Return value:
If the player's inventory contains enough resource units to manufacture then the items are manufactured, the resource units required are deducted, and the function returns TRUE. Otherwise no items are manufactured. and the function returns FALSE.

See Also:
 iCargo.eCargoType


iInventory.ManufactureUnits

Return the total of the player's manufacture units..

prototype int iInventory.ManufactureUnits();

Parameters:
None.

Return value:
Returns the player's current manufacture point total.


iInventory.Recycle

Recycle an item or items from the player's inventory, by converting the item(s) into resource points.

prototype bool iInventory.Recycle( eCargoType item, int quantity );

Parameters:
item : The enum for the item to recycle.
quantity : The quantity of that item to recycle.

Return value:
If the player's inventory contains at least quantity of the item then that many items are recycled and the function returns TRUE. If the inventory does not, then no items are recycled and the function returns FALSE.

If items are recycled, the player's resource point total is increased by the number of items recycled multiplied by the resource value per item.

See Also:
 iCargo.eCargoType


iInventory.Remove

Remove an item or items from the player's inventory.

prototype bool iInventory.Remove( eCargoType item, int quantity );

Parameters:
item : The enum for the item to remove.
quantity : The quantity of that item to remove.

Return value:
If the player's inventory contains at least quantity of the item then that many items are removed and the function returns TRUE. If the inventory does not, then no items are removed and the function returns FALSE.

See also:
iInventory.Add, iInventory.AddWithoutMarkingNew, iCargo.eCargoType


iInventory.SetBlueprintsForCargo

Forge the links between blueprints and the cargo which they manufacture.

prototype iInventory.SetBlueprintsForCargo( eCargoType cargo_type, eCargoType blueprints );

Parameters:
cargo_type : The cargo type to manufacture.
blueprints : The blueprints that allow you to manufacture the cargo.

Return value:
TRUE if the player has blueprints for the specified cargo type. FALSE otherwise.

See also:
iInventory.GotBlueprints, iCargo. eCargoType


iInventory.TotalWorth

Return the total worth of the player's inventory.

prototype int iInventory.TotalWorth();

Parameters:
None.

Return value:
Returns the total worth of the player's inventory, which is the sum of the sell values of all the items in the player's inventory.


iInventory.CargoCategoryFromName

Return the cargo category from a cargo's name.

prototype eCargoCategory iInventory.CargoCategoryFromName( string cargo_name );

Parameters:
cargo_name : The cargo name to find the category for.

Return value:
The enum for the cargo category, or 0 if no cargo category is found.

See Also:
 iInventory.eCargoCategory, iCargo.eCargoSuperSet, iInventory.CargoTypeFromName, iInventory.CargoSuperTypeFromName, iInventory.CargoTypeFromCategoryIndex, iInventory.CargoTypeFromSuperTypeIndex.


iInventory.CargoSuperTypeFromName

Return the cargo super type from the cargo name.

prototype eCargoSuperSet iInventory.CargoSuperTypeFromName( string cargo_name );

Parameters:
cargo_name : The cargo name to find the super set for.

Return value:
The enum for the cargo super set, or 0 if no cargo is found.

See Also:
 See Also:
 iCargo.eCargoSuperSet, iInventory.CargoTypeByName, iInventory.CargoCategoryFromName, iInventory.CargoSuperTypeFromName, iInventory.CargoTypeFromCategoryIndex, iInventory.CargoTypeFromSuperTypeIndex.


iInventory.CargoTypeCategoryIndex

Return the cargo type from a cargo category index.

prototype eCargoType iInventory.CargoTypeCategoryIndex( int index );

Parameters:
index : The index in the category.

Return value:
The cargo type

See Also:
 iCargo.eCargoType, iInventory.CargoTypeFromName, iInventory.CargoCategoryFromName, iInventory.CargoSuperTypeFromName, iInventory.CargoTypeFromSuperTypeIndex.


iInventory.CargoTypeFromName

Return the cargo type from a cargo's name.

prototype eCargoType iInventory.CargoTypeFromName( string cargo_name );

Parameters:
cargo_name : The cargo name to find the type for.

Return value:
The cargo type as an int, or 0 if no cargo type is found.

See Also:
 iCargo.eCargoType, iCargo.eCargoSuperSet, iInventory.CargoCategoryFromName, iInventory.CargoSuperTypeFromName, iInventory.CargoTypeFromCategoryIndex, iInventory.CargoTypeFromSuperTypeIndex.


iInventory.CargoTypeSupertypeIndex

Return the cargo type from a super set index.

prototype eCargoType iInventory.CargoTypeSupertypeIndex( int index );

Parameters:
index : The index in the super set.

Return value:
The cargo type.

See Also:
 iCargo.eCargoType, iInventory.CargoTypeFromName, iInventory.CargoCategoryFromName, iInventory.CargoSuperTypeFromName, iInventory.CargoTypeFromCategoryIndex.


iInventory.CategoryContaining

Find the category containing a particular cargo type.

prototype eCargoCategory iInventory.CategoryContaining( eCargoType cargo_type );

Parameters:
cargo_type : The cargo type to find the category for.

Return value:
The cargo type as an int, or 0 if no cargo type is found.

See Also:
 iCargo.eCargoType, iCargo.eCargoCategory, iInventory.SuperSetContaining


iInventory.CreateCargoCategory

Create a new cargo category.

prototype iInventory.CreateCargoCategory( int category_id,
                      string category_name_key,
                          string encyclopaedia_entry,
                      eCargoType start_type,
                      eCargoType end_type );

Parameters:
category_id : The ID of the category to create.
category_name_key : The text key for the category name.
encyclopedia_entry : The Encyclopedia entry URL.
start_type : The first cargo pod type in the category.
end_type : The final cargo pod type in the category.

Return value:
None

Notes:
Only one category can be created with a given ID number - all subsequent categories will be ignored.
All cargoes in the same category must have adjacent type numbers.

See Also:
 iCargo.eCargoType, CreateCargoSuperset


iInventory.CreateCargoSuperSet

Create a new cargo super set. This is the top level of cargo categorisation.

prototype iInventory.CreateCargoCategory( int superset_id,
                      string super_set_name_key,
                          string encyclopaedia_entry,
                      eCargoCategory start_category,
                      eCargoCategory end_category );

Parameters:
super_set_id : The ID of the super set to create.
super_set_name_key : The text key for the category name.
encyclopedia_entry : The Encyclopedia entry URL.
start_category : The first cargo pod category in the set.
end_tcategory : The final cargo pod category in the set.

Return value:
None

Notes:
Only one super set can be created with a given ID number - all subsequent super sets will be ignored.
All categories in the same super set must have adjacent type numbers.

See Also:
 iInventory.eCargoCategory, CreateCargoCategory


iInventory.NumberOfCargoTypes

Find the total number of cargo types available.

prototype int iInventory.NumberOfCargoTypes();

Parameters:
None

Return value:
The number of cargo types as an int.

See Also:
iInventory.NumTypesInInventory


iInventory.NumberOfCargoInCategory

How many of any cargo in a given category does the player have?

prototype int iInventory.NumberOfCargoInCategory( eCargoCategory category );

Parameters:
category : The Enum of the cargo category.

Return value:
The number of cargo.

See Also:
iInventory.eCargoCategory, iInventory.NumberOfRecyclableCargoInCategory


iInventory.NumberOfCargoInSuperSet

How many of any cargo in a given super set does the player have?

prototype int iInventory.NumberOfCargoInSuperSet( eCargoSuperSet super_set );

Parameters:
super_set : The Enum of the cargo super set.

Return value:
The number of cargo.

See Also:
iInventory.eCargoCategory, iInventory.NumberOfRecyclableCargoInSuperSet


iInventory.NumberOfRecyclableCargoInCategory

How many of any recyclable cargo in a given category does the player have?

prototype int iInventory.NumberOfRecyclableCargoInCategory( eCargoCategory category );

Parameters:
category : The Enum of the cargo category.

Return value:
The number of cargo.

See Also:
iInventory.eCargoCategory, iInventory.NumberOfCargoInCategory, iInventory.NumberOfRecyclableCargoInSuperSet, iInventory.NumberOfCargoInSuperSet


iInventory.NumberOfRecyclableCargoInSuperSet

How many of any recyclable cargo in a given super set does the player have?

prototype int iInventory.NumberOfRecyclableCargoInSuperSet( eCargoSuperSet super_set );

Parameters:
super_set : The Enum of the cargo super set.

Return value:
The number of cargo.

See Also:
iInventory.eCargoCategory, iInventory.NumberOfCargoInSuperSet, iInventory.NumberOfCargoInCategory, iInventory.NumberOfRecyclableCargoInCategory


iInventory.NumTypesInCategory

Find the total number of different cargo types the player has in a given category

prototype int iInventory.NumTypesInSuperSet( eCargoCategory category );

Parameters:
category : The Enum of the cargo category.

Return value:
The number of cargo types as an int.

See Also:
 iInventory.eCargoCategory, iInventory.QuantityOfNthTypeInInventory, iInventory.QuantityOfNthTypeInCategory, iInventory.QuantityOfNthTypeInSuperSet, iInventory.NumTypesInInventory, iInventory.NumTypesInSuperSet


iInventory.NumTypesInInventory

Find the total number of different cargo types the player has in his inventory.

prototype int iInventory.NumTypesInInventory();

Parameters:
None

Return value:
The number of cargo types as an int.

See Also:
 iInventory.QuantityOfNthTypeInInventory, iInventory.QuantityOfNthTypeInCategory, iInventory.QuantityOfNthTypeInSuperSet, iInventory.NumTypesInInventory, iInventory.NumTypesInCategory, iInventory.NumTypesInSuperSet


iInventory.NumTypesInSuperSet

Find the total number of different cargo types the player has in a given super set.

prototype int iInventory.NumTypesInSuperSet( eCargoSuperSet super_set );

Parameters:
super_set : The Enum of the cargo super set.

Return value:
The number of cargo types as an int.

See Also:
 iInventory.eCargoSuperSet, iInventory.QuantityOfNthTypeInInventory, iInventory.QuantityOfNthTypeInCategory, iInventory.QuantityOfNthTypeInSuperSet, iInventory.NumTypesInInventory, iInventory.NumTypesInCategory


iInventory.QuantityOfNthTypeInCategory

Return the quantity of a cargo type from the nth item in a superset

prototype int iInventory.QuantityOfNthTypeInCategory( int index, eCargoCategory category );

Parameters:
index : The index in the category.
category : The Enum of the cargo category.

Return value:
The quantity of that cargo type in the category.

See Also:
 iInventory.eCargoCategory, iInventory.QuantityOfNthTypeInInventory, iInventory.QuantityOfNthTypeInSuperSet, iInventory.NumTypesInInventory, iInventory.NumTypesInCategory, iInventory.NumTypesInSuperSet


iInventory.QuantityOfNthTypeInInventory

Return the quantity of a cargo type from a cargo type index value.

prototype int iInventory.QuantityOfNthTypeInInventory( int index );

Parameters:
index : The index in the cargo types.

Return value:
The quantity in the inventory.

See Also:
 iInventory.QuantityOfNthTypeInInventory, iInventory.QuantityOfNthTypeInCategory, iInventory.QuantityOfNthTypeInSuperSet, iInventory.NumTypesInInventory, iInventory.NumTypesInCategory, iInventory.NumTypesInSuperSet


iInventory.QuantityOfNthTypeInSuperSet

Return the quantity of a cargo type from the nth item in a superset

prototype int iInventory.QuantityOfNthTypeInSuperSet( int index, eCargoSuperSet super_set );

Parameters:
index : The index in the category.
super_set : The Enum of the cargo super set.

Return value:
The quantity of that cargo type in the superset.

See Also:
 iInventory.eCargoSuperSet, iInventory.QuantityOfNthTypeInInventory, iInventory.QuantityOfNthTypeInCategory, iInventory.QuantityOfNthTypeInSuperSet, iInventory.NumTypesInInventory, iInventory.NumTypesInCategory, iInventory.NumTypesInSuperSet


iInventory.SuperSetContaining

Find the super set containing a particular cargo category.

prototype eCargoSuperSet iInventory.SuperSetContaining( eCargoCategory category );

Parameters:
category : The cargo category to find the super set for.

Return value:
The cargo super set.

See Also:
 iCargo.eCargoSuperSet, iCargo.eCargoCategory, iInventory.CategoryContaining


iInventory.FillAddCargoListBox

Fill the given list box with inventory description windows for the add cargo screen. Also fill a list of cargo handles representing each added list box entry.

prototype iInventory.FillAddCargoListBox( hwindow list_box, ref list cargo );

Parameters:
list_box : The window list box to fill.
cargo : The list of cargo to use.

Return value:
None

See also:
iInventory.FillInventoryListBox, iInventory.FillRecyclingListBox


iInventory.FillInventoryListBox

Fill the given list box with inventory description windows for the inventory screen. Also fill a list of cargo handles representing each added list box entry.

prototype iInventory.FillInventoryListBox( hwindow list_box,
                       bool player_systems,
                       ref list cargo );

Parameters:
list_box : The window list box to fill.
player_systems : TRUE to use only player systems, FALSE otherwise.
cargo : The list of cargo to use.

Return value:
None

See also:
iInventory.FillInventoryListBox, iInventory.FillAddCargoListBox


iInventory.FillRecyclingListBox

Fill the given list box with inventory description windows for the recycling screen. Also fill a list of cargo handles representing each added list box.

prototype iInventory.FillRecyclingListBox( hwindow list_box, ref list cargo );

Parameters:
list_box : The window list box to fill.
cargo : The list of cargo to use.

Return value:
None

See also:
iInventory.FillInventoryListBox, iInventory.FillAddCargoListBox


iInventory.ResetWindows

Pull the inventory windows out of their existing window manager and back into the inventory.

prototype iInventory.ResetWindows();

Parameters:
None.

Return value:
None.


iInventory.AddCommandSection

Add the Command Section to the player's inventory.

prototype iInventory.AddCommandSection();

Parameters:
None

Return value:
None

See Also:
iInventory.AddFastAttackShip, iInventory.AddHeavyCorvette, iInventory.AddStormPetrel, iInventory.AddTug, iInventory.RemoveCommandSection, iInventory.RemoveFastAttackShip, iInventory.RemoveHeavyCorvette, iInventory.RemoveStormPetrel, iInventory.RemoveTug


iInventory.AddFastAttackShip

Add the Advanced Patcom (AKA the Fast Attack Ship) to the player's inventory.

prototype iInventory.AddFastAttackShip();

Parameters:
None

Return value:
None

See Also:
iInventory.AddCommandSection, iInventory.AddHeavyCorvette, iInventory.AddStormPetrel, iInventory.AddTug, iInventory.RemoveCommandSection, iInventory.RemoveFastAttackShip, iInventory.RemoveHeavyCorvette, iInventory.RemoveStormPetrel, iInventory.RemoveTug


iInventory.AddHeavyCorvette

Add the Heavy Corvette to the player's inventory.

prototype iInventory.AddHeavyCorvette();

Parameters:
None

Return value:
None

See Also:
iInventory.AddCommandSection, iInventory.AddFastAttackShip, iInventory.AddStormPetrel, iInventory.AddTug, iInventory.RemoveCommandSection, iInventory.RemoveFastAttackShip, iInventory.RemoveHeavyCorvette, iInventory.RemoveStormPetrel, iInventory.RemoveTug


iInventory.AddStormPetrel

Add the Storm Petrel to the player's inventory.

prototype iInventory.AddStormPetrel();

Parameters:
None

Return value:
None

See Also:
iInventory.AddCommandSection, iInventory.AddFastAttackShip, iInventory.AddHeavyCorvette, iInventory.AddTug, iInventory.RemoveCommandSection, iInventory.RemoveFastAttackShip, iInventory.RemoveHeavyCorvette, iInventory.RemoveStormPetrel, iInventory.RemoveTug


iInventory.AddTug

Add the Tug to the player's inventory.

prototype iInventory.AddTug();

Parameters:
None

Return value:
None

See Also:
iInventory.AddCommandSection, iInventory.AddFastAttackShip, iInventory.AddHeavyCorvette, iInventory.AddStormPetrel, iInventory.RemoveCommandSection, iInventory.RemoveFastAttackShip, iInventory.RemoveHeavyCorvette, iInventory.RemoveStormPetrel, iInventory.RemoveTug


iInventory.GotCommandSection

Find out if the player has got the Command Section

prototype bool iInventory.GotCommandSection();

Parameters:
None

Return value:
TRUE if the player has got the ship, false otherwise.

See Also:
iInventory.GotFastAttackShip, iInventory.GotHeavyCorvette, iInventory.GotStormPetrel, iInventory.GotTug


iInventory.GotFastAttackShip

Find out if the player has got the Advanced Patcom, AKA the Fast Attack Ship..

prototype bool iInventory.GotFastAttackShip();

Parameters:
None

Return value:
TRUE if the player has got the ship, false otherwise.

See Also:
iInventory.GotCommandSection, iInventory.GotHeavyCorvette, iInventory.GotStormPetrel, iInventory.GotTug


iInventory.GotHeavyCorvette

Find out if the player has got the Heavy Corvette

prototype bool iInventory.GotHeavyCorvette();

Parameters:
None

Return value:
TRUE if the player has got the ship, false otherwise.

See Also:
iInventory.GotCommandSection, iInventory.GotFastAttackShip, iInventory.GotStormPetrel, iInventory.GotTug


iInventory.GotStormPetrel

Find out if the player has got the Storm Petrel

prototype bool iInventory.GotStormPetrel();

Parameters:
None

Return value:
TRUE if the player has got the ship, false otherwise.

See Also:
iInventory.GotCommandSection, iInventory.GotFastAttackShip, iInventory.GotHeavyCorvette, iInventory.GotTug


iInventory.GotTug

Find out if the player has got the Tug.

prototype bool iInventory.GotTug();

Parameters:
None

Return value:
TRUE if the player has got the ship, false otherwise.

See Also:
iInventory.GotCommandSection, iInventory.GotFastAttackShip, iInventory.GotHeavyCorvette, iInventory.GotStormPetrel


iInventory.RemoveCommandSection

Remove the Command Section from the player's inventory.

prototype iInventory.RemoveCommandSection();

Parameters:
None

Return value:
None

See Also:
iInventory.RemoveFastAttackShip, iInventory.RemoveHeavyCorvette, iInventory.RemoveStormPetrel, iInventory.RemoveTug


iInventory.RemoveFastAttackShip

Remove the Advanced Patcom (AKA the Fast Attack Ship) from the player's inventory.

prototype iInventory.RemoveFastAttackShip();

Parameters:
None

Return value:
None

See Also:
iInventory.RemoveCommandSection, iInventory.RemoveHeavyCorvette, iInventory.RemoveStormPetrel, iInventory.RemoveTug


iInventory.RemoveHeavyCorvette

Remove the Heavy Corvette from the player's inventory.

prototype iInventory.RemoveHeavyCorvette();

Parameters:
None

Return value:
None

See Also:
iInventory.RemoveCommandSection, iInventory.RemoveFastAttackShip, iInventory.RemoveStormPetrel, iInventory.RemoveTug


iInventory.RemoveTug

Remove the Tug from the player's inventory.

prototype iInventory.RemoveTug();

Parameters:
None

Return value:
None

See Also:
iInventory.RemoveCommandSection, iInventory.RemoveFastAttackShip, iInventory.RemoveHeavyCorvette, iInventory.RemoveStormPetrel


iInventory.RemoveStormPetrel

Remove the Storm Petrel from the player's inventory.

prototype iInventory.RemoveStormPetrel();

Parameters:
None

Return value:
None

See Also:
iInventory.RemoveCommandSection, iInventory.RemoveFastAttackShip, iInventory.RemoveHeavyCorvette, iInventory.RemoveTug


iLoadout

This package allows the control of the player ship loading out system.

Type definitions:

  • eLoadout
  • eRearmSuccess
  • eShip

Functions:

Loadout Management

These functions deal with managing loadouts.

  • CalculateLoadout
  • CurrentLoadout
  • GoodToGo
  • LoadoutActive
  • LoadoutDescription
  • LoadoutFromInt
  • LoadoutName
  • RegisterAmmoType
  • RemoteFighterMounted
  • RemoveRemoteFighter
  • RemoveTurretFighters
  • SetDesiredNumberOfTurretFighters
  • TurretFightersInLoadout
  • UnusedInternalCargoSlots

Ship Management

These functions deal with managing the ship to be loaded out.

  • Cargo
  • RearmFromJaffs
  • RearmFromThirdParty
  • SetCargo
  • SetShip
  • Ship
  • ShipName
  • ShipTypeName
  • StripShip
  • StripTurretFighters

Customised Loadout Functions

These highly specialised functions deal with the customised loadout function.

  • CargoSpaceWarning
  • CustomisedLoadoutMode
  • EndCustomisedLoadout
  • OnCustomiseScreenBack
  • OnCustomiseScreenSelect
  • StartCustomisedLoadout
  • UpdateCustomisedLoadout

Window Management

  • SetManifestWindow

Notes:

The majority of these functions are designed to be used by the loadout scripts in the player base, and are in general highly specialised.


iLoadout.eLoadout

This enumeration is used for the different loadout options.

enum eLoadout
{
    L_Empty,
    L_Standard,
    L_Assault,
    L_Stealth,
    L_ECM,
    L_Custom1,
    L_Custom2,
    L_Count
};

Notes:
The declaration of this enumeration can be found in iLoadout.h.


iLoadout.eRearmSuccess

This enumeration is used for showing the success of a re-arming operation.

enum eRearmSuccess
{
    RS_CompleteRefit,
    RS_PartialRefit,
    RS_NoRefitPossible,
    RS_RefitUnnecessary
};

Notes:
The declaration of this enumeration can be found in iLoadout.h.


iLoadout.eShip

This enumeration is used for the different ship types.

enum eCamera
{
    enum eShip
{
    S_CommandSection,
    S_Tug,
    S_FastAttackShip,
    S_HeavyCorvette,
    S_StormPetrel,
    S_Count
};

Notes:
The declaration of this enumeration can be found in iLoadout.h.


iLoadout.CalculateLoadout

Work out the ship loadout best suited to the given loadout choice.

prototype eLoadout iLoadout.CalculateLoadout(eLoadout loadout )

Parameters:
loadout : The loadout to calculate.

Return value:
None.


iLoadout.CurrentLoadout

Get the current loadout for the chosen ship.

prototype eLoadout iLoadout.CurrentLoadout()

Parameters:
None

Return value:
The Loadout enum.

See Also:
iLoadout.eLoadout, iLoadout.LoadoutName


iLoadout.GoodToGo

Checks to see if a ship is chosen and the loadout is valid.

prototype bool iLoadout.GoodToGo()

Parameters:
None

Return value:
TRUE if it's good to go, FALSE if not.


iLoadout.LoadoutActive

Checks to see if a loadout is active.

prototype bool iLoadout.LoadoutActive()

Parameters:
None

Return value:
TRUE if a loadout is active, FALSE if not.


iLoadout.Description

Get a HTML description of the specified loadout.

prototype string iLoadout.CurrentLoadout( eLoadout loadout )

Parameters:
loadout : The loadout to get the description for.

Return value:
The Loadout enum.

See Also:
iLoadout.eLoadout, iLoadout.Name


iLoadout.LoadoutFromInt

Convert the loadout from an int to a member of the loadout enumeration.

prototype eLoadout iLoadout.LoadoutFromInt( int loadout );

Parameters:
loadout : The loadout to convert.

Return value:
The Loadout enum.

See Also:
iLoadout.eLoadout


iLoadout.LoadoutName

Get the name for the specified loadout.

prototype string iLoadout.CurrentLoadout( eLoadout loadout )

Parameters:
loadout : The loadout to find the name for.

Return value:
The Loadout enum.

See Also:
iLoadout.eLoadout, iLoadout.CurrentLoadout, iLoadout.LoadoutDescription


iLoadout.RegisterAmmoType

Register a type of ammo by the template of it's launcher or gun.

prototype iLoadout.RegisterAmmoType( string weapon_template );

Parameters:
weapon_template : The URL of the weapon template.

Return value:
None.


iLoadout.RemoteFighterMounted

Checks to see if a remote fighter is loaded onto the ship.

prototype bool iLoadout.RemoteFighterMounted();

Parameters:
None

Return value:
TRUE if a remote fighter is loaded, FALSE if not.

See Also:
iLoadout.RemoveRemoteFighter


iLoadout.RemoveRemoteFighter

Remove a remote fighter from the ship ( if loaded ).

prototype bool iLoadout.RemoveRemoteFighter();

Parameters:
None

Return value:
None

See Also:
iLoadout.RemoteFighterMounted


iLoadout.RemoveTurretFighters

Take the existing loadout and remove any T-fighters from it.

prototype bool iLoadout.RemoveTurretFighters();

Parameters:
None

Return value:
None

Notes:
This is needed whenever we plan to make the T-Fighters unavailable for a mission - you remove them from the loadout and then remove them from the inventory.

See Also:
iLoadout.TurretFightersInLoadout, iLoadout.SetDesiredNumberOfTurretFighters


iLoadout.SetDesiredNumberOfTurretFighters

Convert the loadout from an int to a member of the loadout enumeration.

prototype iLoadout.SetDesiredNumberOfTurretFighters( int fighters );

Parameters:
fighters : The number of fighters.

Return value:
None

Notes:
A maximum of two turret fighters can be loaded onto a player ship.

See Also:
iLoadout.RemoveTurretFighters, iLoadout.TurretFightersInLoadout


iLoadout.TurretFightersInLoadout

Get the number of turret fighters loaded out on the player ship

prototype int iLoadout.TurretFightersInLoadout();

Parameters:
None

Return value:
The number of turret fighters loaded onto the ship.

See Also:
iLoadout.RemoveTurretFighters, iLoadout.SetDesiredNumberOfTurretFighters


iLoadout.UnusedInternalCargoSlots

Get the spare internal cargo slots

prototype int iLoadout.UnusedInternalCargoSlots();

Parameters:
None

Return value:
The number of internal cargo slots free.

Notes:
Some weapons use internal cargo space, as well as external mounts. This command is used to find how many internal cargo slots are free for those weapons.

See Also:
iLoadout.eLoadout


iLoadout.Cargo

Get the cargo to attach to the player ship.

prototype eCargoType iLoadout.SetCargo();

Parameters:
None

Return value:
The cargo type enum.

See Also:
iCargo.eCargoType, iLoadout.SetCargo


iLoadout.RearmFromJaffs

Attempt to rearm any ammo limited weapons from the player's inventory.

prototype eRearmSuccess iLoadout.RearmFromJaffs( hship ship )

Parameters:
ship : The handle of the player's ship to rearm.

Return value:
An enum detailing the success of the rearming.

Notes:
This function was written to allow the player to rearm from Jafs by docking to him, but was never used. Note the misspelling of Jafs in the function name.

See Also:
iLoadout.eRearmSuccess, iLoadout.RearmFromThirdParty


iLoadout.RearmFromThirdParty

Attempt to rearm any ammo limited weapons from a third party.

prototype eRearmSuccess iLoadout.RearmFromJaffs( hship ship, float refit_limit )

Parameters:
ship : The handle of the player's ship to rearm.
refit_limit : A float betwen 0 and 1, defining what proportion of the total capacity of the weapon will be refilled.

Return value:
An enum detailing the success of the rearming.

Notes:
Here's an example of how the refit_limit works: If the refit limit was 0.5 then an assault cannon with a capacity of 1000 rounds will only be topped up by a maximum of 500 rounds.

See Also:
iLoadout.eRearmSuccess, iLoadout.RearmFromThirdParty


iLoadout.SetCargo

Set the cargopod to attach to the player ship.

prototype iLoadout.SetCargo( eCargoType cargo_type );

Parameters:
cargo_type : The type of cargo to add.

Return value:
None.

See Also:
iCargo.eCargoType, iLoadout.Cargo


iLoadout.SetShip

Set the ship to fly.

prototype iLoadout.SetShip( eShip ship )

Parameters:
ship : The ship to fly.

Return value:
None.

See Also:
iLoadout.eShip


iLoadout.Ship

Get the current ship.

prototype eShip iLoadout.Ship()

Parameters:
None

Return value:
The Ship enum.

See Also:
iLoadout.eShip, iLoadout.ShipName


iLoadout.ShipName

Get the name for the specified ship.

prototype string iLoadout.CurrentLoadout( eShip ship )

Parameters:
ship : The ship to find the name for.

Return value:
The ship name.

See Also:
iLoadout.eShip, iLoadout.Ship


iLoadout.ShipTypeName

Get the name of the type of the currently loaded out ship

prototype string iLoadout.ShipTypeName( eShip ship );

Parameters:
ship : The ship to find the type for.

Return value:
The ship type name.

See Also:
iLoadout.eShip, iLoadout.Ship, iLoadout.ShipName


iLoadout.StripShip

Strip the player ship (which is passed in) of all its systems and weapons. This will cancel the current loadout.

prototype iLoadout.StripShip( hship ship )

Parameters:
ship : The handle of the ship to strip.

Return value:
None.

See Also:
iLoadout.StripTurretFighters


iLoadout.StripTurretFighters

Strip the turret fighters all their systems and weapons.

prototype iLoadout.StripTurretFighters( list turret_fighters );

Parameters:
turret_fighters : The list of turret fighters to strip.

Return value:
None.

See Also:
iLoadout.StripShip


iLoadout.CargoSpaceWarning

Find out if we are currently displaying a cargo space warning.

prototype bool iLoadout.CargoSpaceWarning()

Parameters:
None

Return value:
TRUE if we are displaying a cargo space warning, FALSE otherwise.


iLoadout.CustomisedLoadoutMode

Get the current mode for the customised loadout.

prototype int iLoadout.CustomisedLoadoutMode()

Parameters:
None

Return value:
The customised loadout mode as an int.


iLoadout.EndCustomisedLoadout

End a customised loadout session.

prototype iLoadout.EndCustomisedLoadout();

Parameters:
None

Return value:
 None

See Also:
iLoadout.StartCustomisedLoadout, iLoadout.UpdateCustomisedLoadout


iLoadout.OnCustomiseScreenBack

To go back a mode in the customisation.

prototype iLoadout.OnCustomiseScreenBack();

Parameters:
None

Return value:
 None

See Also:
iLoadout.OnCustomiseScreenSelect


iLoadout.OnCustomiseScreenSelect

When an option is selected on the customised loadout screen, this function is called.

prototype iLoadout.OnCustomiseScreenSelect();

Parameters:
None

Return value:
 None

See Also:
iLoadout.OnCustomiseScreenBack


iLoadout.StartCustomisedLoadout

Start a customised loadout. This is done in native code for speed.

prototype iLoadout.StartCustomisedLoadout( hwindow splitter_window, hwindow text_box );

Parameters:
splitter_window : The customised loadout window handle.
text_box : The customised loadout text box handle.

Return value:
 None

See Also:
iLoadout.EndCustomisedLoadout, iLoadout.UpdateCustomisedLoadout


iLoadout.UpdateCustomisedLoadout

Update the customised loadout text box.

prototype iLoadout.UpdateCustomisedLoadout();

Parameters:
None

Return value:
 None

See Also:
iLoadout.StartCustomisedLoadout, iLoadout.EndCustomisedLoadout


iLoadout.SetManifestWindow

Set the manifest window.

prototype iLoadout.SetManifestWindow( hwindow window );

Parameters:
window : The window to set.

Return value:
None.


iMod

The iMod package is used to query and manage user Mods.

Functions:

  • Count
  • DisplayName
  • Enable
  • IsScenario
  • Name
  • ScanDirectory


iMod.Count

Count the number of mods in the mods folder.

prototype int iMod.Count();

Parameters:
None.

Return value:
The number of mods available.


iMod.DisplayName

Get the display name of the Nth mod in the mods folder

prototype string iMod.DisplayName( int n );

Parameters:
n : The number of the mod to find the display name for.

Return value:
The display name of the Nth mod.

See also:
iMod.Count, iMod.Name


iMod.Enable

Enable / disable the Nth mod.

prototype iMod.Enable( int n, bool enable );

Parameters:
n : The number of the mod to check.
enable : TRUE to enable, FALSE to disable.

Return value:
None.

See also:
iMod.Count


iMod.IsScenario

Check if the Nth mod is a scenario.

prototype string iMod.IsScenario( int n );

Parameters:
n : The number of the mod to check.

Return value:
TRUE if the mod is a scenario, false otherwise.

See also:
iMod.Count


iMod.Name

Get the name of the Nth mod in the mods folder

prototype string iMod.Name( int n );

Parameters:
n : The number of the mod to find the name for.

Return value:
The name of the Nth mod.

See also:
iMod.Count, iMod.DisplayName


iMod.ScanDirectory

Build the list of mods.

prototype iRegion.iMod.ScanDirectory();

Parameters:
None

Return value:
None


iOptions

This package allows the manipulation of the game's options.

Functions:

General

  • Apply
  • RestoreDefaults
  • Update

Registration

  • RegisterBool
  • RegisterFloat
  • RegisterInt
  • RegisterString
  • RegisterStringPropertyOption
  • UnregisterAll

Window Management

  • CreateWindows
  • OnLeft
  • OnRight
  • OnSelect

Graphics Options

  • CreateGraphicsDeviceOptionButtons
  • CreateGraphicsResolutionOptionButtons
  • GraphicsDeviceIndex
  • GraphicsResolutionIndex
  • DirectX8Available
  • NumberOfResolutionOptions
  • SetGraphicsDevice

Notes:

The game options are updated inside the game immediately, but are only saved in the appropriate ini files when the game exits.

Many of the functions are highly specialised, and designed for exclusive use with the game's options screen.


iOptions.Apply

Go through the registered options and apply the changes made.

prototype iOptions.Apply();

Parameters:
None
Return value:
None.

See also:
iOptions.Update


iOptions.RestoreDefaults

Restore the default option values.

prototype iOptions.RestoreDefaults();

Parameters:
None.
Return value:
None.


iOptions.Update

Check that the options haven't changed.

prototype iOptions.Apply();

Parameters:
None
Return value:
None.

See also:
iOptions.Apply


iOptions.RegisterInt

Register an int option with the Options screen.

prototype iOptions.RegisterInt( string name,
                 string class_name,
                 string property,
                 bool immediate_update );

Parameters:
name : The name key of the option.
 class_name : The name of the class the option manipulates.
property : The property on the class the option manipulates.
immediate_update : TRUE to update immediately, FALSE to update later.

 Return value:
None.

See also:
iOptions.RegisterFloat, iOptions.RegisterInt, iOptions.RegisterString


iOptions.RegisterFloat

Register a float option with the Options screen.

prototype iOptions.RegisterFloat( string name,
                  string class_name,
                  string property,
                  float start_value,
                  float end_value,
                  bool immediate_update );

Parameters:
name : The name key of the option.
 class_name : The name of the class the option manipulates.
property : The property on the class the option manipulates.
start_value : The lowest value of the option.
end_value : The highest value of the option.
immediate_update : TRUE to update immediately, FALSE to update later.

 Return value:
None.

See also:
iOptions.RegisterInt, iOptions.RegisterBool, iOptions.RegisterString


iOptions.RegisterInt

Register a integer option with the Options screen.

prototype iOptions.RegisterInt( string name,
                string class_name,
                string property,
                float start_value,
                float end_value,
                bool immediate_update );

Parameters:
name : The name key of the option.
 class_name : The name of the class the option manipulates.
property : The property on the class the option manipulates.
start_value : The lowest value of the option.
end_value : The highest value of the option.
immediate_update : TRUE to update immediately, FALSE to update later.

 Return value:
None.

See also:
iOptions.RegisterFloat, iOptions.RegisterBool, iOptions.RegisterString


iOptions.RegisterString

Register a string option with the Options screen.

prototype iOptions.RegisterString( string name,
                   string class_name,
                   string property,
                   string first_option,
                   bool immediate_update );

Parameters:
name : The name key of the option.
 class_name : The name of the class the option manipulates.
property : The property on the class the option manipulates.
first_option : The first string option.
end_value : The highest value of the option.
immediate_update : TRUE to update immediately, FALSE to update later.

 Return value:
None.

Notes:
This command is used with iOptions.RegisterStringPropertyOption.

See also:
iOptions.RegisterStringPropertyOption, iOptions.RegisterFloat, iOptions.RegisterBool, iOptions.RegisterInt


iOptions.RegisterStringPropertyOption

Register an string property to a string option. This is needed because Pog does not support lists of strings.

prototype iOptions.RegisterStringPropertyOption( string name,
                         string value );

Parameters:
name : The name key of the option.
 value : The value of the string.

 Return value:
None.

See also:
iOptions.RegisterString


iOptions.UnregisterAll

Unregister all the registered options.

prototype iOptions.UnregisterAll();

Parameters:
None
Return value:
None.

See also:
iOptions.RegisterBool, iOptions.RegisterFloat, iOptions.RegisterInt, iOptions.RegisterString


iOptions.CreateWindows

Create the windows to display and control the option settings for the registered options.

prototype iOptions.CreateWindows( hwindow list_box );

Parameters:
list_box : The list box for the option windows.

 Return value:
None.

See also:
iOptions.RegisterFloat, iOptions.RegisterInt, iOptions.RegisterString


iOptions.OnLeft

Perform this function when the list box entries get a left command.

prototype iOptions.OnLeft( hwindow list_box );

Parameters:
list_box : The options list box.

 Return value:
None.

See also:
iOptions.OnSelect, iOptions.OnRight


iOptions.OnRight

Perform this function when the list box entries get a right command.

prototype iOptions.OnRight( hwindow list_box );

Parameters:
list_box : The options list box.

 Return value:
None.

See also:
iOptions.OnSelect, iOptions.OnLeft


iOptions.OnSelect

Perform this function when the list box entries get selected.

prototype iOptions.OnSelect( hwindow list_box );

Parameters:
list_box : The options list box.

 Return value:
None.

See also:
iOptions.OnLeft, iOptions.OnRight


iOptions.CreateGraphicsDeviceOptionButtons

Create a list of parentless, list-box-ready buttons for the various supported graphics devices.

prototype list iOptions.CreateGraphicsDeviceOptionButtons();

Parameters:
None.
Return value:
A list of buttons.

See also:
iOptions.CreateGraphicsResolutionOptionsButtons


iOptions.CreateGraphicsResolutionOptionButtons

Create a list of parentless, list-box-ready buttons for the various supported graphics resolution. Also pass in whether or not we want thin buttons (because of a scrollbar).

prototype list iOptions.CreateGraphicsResolutionOptionButtons( int device_index,
                                   bool thin_buttons );

Parameters:
device_index : The graphics device index to create buttons for.
 thin_buttons : TRUE for thin buttons, FALSE for wide buttons.
Return value:
The number of resolution options.

See also:
iOptions.CreateGraphicsDeviceOptionButtons


iOptions.DirectX8Available

Check if DirectX 8 functionality is available

prototype bool iOptions.DirectX8Available();

Parameters:
None
Return value:
TRUE if DirectX8 functionality is available, FALSE otherwise.


iOptions.GraphicsDeviceIndex

Get the index into the list of graphics devices of the selected device.

prototype int iOptions.GraphicsDeviceIndex();

Parameters:
None.
Return value:
The graphics device index.

See also:
iOptions.GraphicsResolutionIndex


iOptions.GraphicsResolutionIndex

Get the index into the list of graphics resolutions of the selected device.

prototype int iOptions.GraphicsResolutionIndex( int device_index );

Parameters:
device_index : The graphics device index to find the graphic resolution index for.
Return value:
The graphics resolution index.

See also:
iOptions.GraphicsDeviceIndex


iOptions.NumberOfResolutionOptions

Get the number of resolution options.

prototype int iOptions.NumberOfResolutionOptions( int device_index );

Parameters:
device_index : The graphics device index to find the number of resolution options for.
Return value:
The number of resolution options.

See also:
iOptions.SetGraphicsDevice


iTrade

The trading system in I-War 2 is barter based, and this package allows the creation, manipulation and querying of trades.

Type definitions:

  • htrade

Functions:

General

  • Cast

Trade Creation and Manipulation

These functions deal with the creation and manipulation of trades.

  • CreateTradeForCargoCategory
  • CreateTradeForCargoSuperSet
  • CreateTradeForCargoType
  • OfferTrade
  • PerformTrade
  • RemoveTrade

Querying Trades

These functions deal with the querying of trades.

  • CanSatisfyTrade
  • Faction
  • MetatypeOfTrade
  • NumOffers
  • NthTrade
  • NumTrades
  • Offered
  • Wanted

Jafs

These functions deal with the Jafs information box on the Trade screen.

  • iTrade.JaffsTradeAdvice
  • iTrade.JaffsTradeDescription


iTrade.htrade

I-War II trade handle.

htrade : hobject;


iTrade.Cast

Cast an hobject handle to an htrade handle.

prototype htrade iTrade.Cast( hobject the_handle );

Parameters:
the_handle : The handle to cast to an htrade handle.

Return value:
Returns a htrade handle. Returns none if the handle would not be a valid htrade.

See also:
iTrade.htrade


iTrade.CreateTradeForCargoCategory

Create a trade for a cargo category. The trade is offered by the given faction, and consists of an offer of a given number of a given cargo in exchange for a given number of any cargo from the given cargo category.

prototype htrade iTrade.CreateTradeForCargoCategory(
                 hfaction offering_faction,
                 eCargoType cargo_type_offered,
                 int num_offered,
                 eCargoCategory cargo_category_wanted,
                 int num_wanted,
                 int offers );

Parameters:
offering_faction : The handle of the faction offering the trade.
cargo_type_offered : The enum of the cargo type offered.
num_offered : The number of cargo pods offered.
cargo_category_wanted : The enum of the cargo category wanted.
num_wanted : The number of cargo pods wanted.
offers : How many times this trade can be repeated.

Return value:
Returns the trade handle.

Notes:
Once created, the trade must be offered for the player to see it in their trade list.

See also:
iTrade.CreateTradeForCargoType, iTrade.CreateTradeForCargoSuperSet, iCargo.eCargoType, iInventory.eCargoCategory, iTrade.OfferTrade


iTrade.CreateTradeForCargoSuperSet

Create a trade for a cargo super set. The trade is offered by the given faction, and consists of an offer of a given number of a given cargo in exchange for a given number of any cargo from the given cargo super set.

prototype htrade iTrade.CreateTradeForCargoSuperSet(
                 hfaction offering_faction,
                 eCargoType cargo_type_offered,
                 int num_offered,
                 eCargoSuperSet, cargo_superset_wanted,
                 int num_wanted,
                 int offers );

Parameters:
offering_faction : The handle of the faction offering the trade.
cargo_type_offered : The enum of the cargo type offered.
num_offered : The number of cargo pods offered.
cargo_superset_wanted : The enum of the cargo category wanted.
num_wanted : The number of cargo pods wanted.
offers : How many times this trade can be repeated.

Return value:
Returns the trade handle.

Notes:
Once created, the trade must be offered for the player to see it in their trade list.

See also:
iTrade.CreateTradeForCargoType, iTrade.CreateTradeForCargoCategory, iCargo.eCargoType, iInventory.eCargoSuperSet, iTrade.OfferTrade


iTrade.CreateTradeForCargoType

Create a trade for a specific cargo type. The trade is offered by the given faction, and consists of an offer of a given number of a given cargo in exchange for a given number of another cargo. Finally, how many times can this trade be taken advantage of.

prototype htrade iTrade.CreateTradeForCargoType( hfaction offering_faction,
                         eCargoType cargo_type_offered,
                         int num_offered,
                         int cargo_type_wanted,
                         int num_wanted,
                         int offers );

Parameters:
offering_faction : The handle of the faction offering the trade.
cargo_type_offered : The enum of the cargo type offered.
num_offered : The number of cargo pods offered.
cargo_type_wanted : The enum of the cargo type wanted.
num_wanted : The number of cargo pods wanted.
offers : How many times this trade can be repeated.

Return value:
Returns the trade handle.

Notes:
Once created, the trade must be offered for the player to see it in their trade list.

See also:
iTrade.CreateTradeForCargoCategory, iTrade.CreateTradeForCargoSuperSet, iCargo.eCargoType, iTrade.OfferTrade


iTrade.OfferTrade

Offer a trade to the player.

prototype iTrade.OfferTrade( htrade trade );

Parameters:
trade : The handle of the trade.

Return value:
None.

Notes:
 The trade must first have been created by one of the trade creation functions. (See below).

See also:
iTrade.RemoveTrade, iTrade.CreateTradeForCargoCategory, iTrade.CreateTradeForCargoSuperSet, iTrade.CreateTradeForCargoType


iTrade.PerformTrade

Action the given trade. The item(s) are swapped instantly.

prototype iTrade.PerformTrade( htrade trade );

Parameters:
trade : The handle of the trade.

Return value:
None.

See also:
iTrade.OfferTrade


iTrade.RemoveTrade

Remove a trade from the player's current trade opportunities.

prototype iTrade.RemoveTrade( htrade trade );

Parameters:
trade : The handle of the trade.

Return value:
None.

Notes:
 The trade must first have been created by one of the trade creation functions. (See below).

See also:
iTrade.OfferTrade, iTrade.CreateTradeForCargoCategory, iTrade.CreateTradeForCargoSuperSet, iTrade.CreateTradeForCargoType


iTrade.CanSatisfyTrade

Check if the player can satisfy the given trade.

prototype bool iTrade.CanSatisfyTrade( htrade trade );

Parameters:
trade : The handle of the trade.

Return value:
TRUE if the player can satisfy the given trade, FALSE otherwise.


iTrade.Faction

Get the offering faction for a trade.

prototype hfaction iTrade.Faction( htrade trade );

Parameters:
trade : The handle of the trade.

Return value:
Returns the handle of the offering faction.

See also:
iTrade.NumOffers, iFaction, iTrade.Wanted, iTrade.Offered


iTrade.MetatypeOfTrade

Find out the metatype of the current trade.

prototype int iTrade.MetatypeOfTrade( htrade trade );

Parameters:
trade : The handle of the trade.

Return value:
Returns an int showing the metatype of the current trade:

0: Cargo
1: Category
2: Superset


iTrade.NumOffers

Find out how many times a trade can be taken advantage of.

prototype int iTrade.NumOffers( htrade trade );

Parameters:
trade : The handle of the trade.

Return value:
Returns the number of times a player can take advantage of the trade.

See also:
iTrade.Faction, iTrade.Offered, iTrade.Wanted


iTrade.NthTrade

Get the nth trade in the list of offered trades.

prototype htrade iTrade.NthTrade( int index );

Parameters:
index : The number of the offered trade.

Return value:
The nth offered trade.

See also:
 iTrade.NumTrades


iTrade.NumTrades

Find out how many trades are currently offered to the player.

prototype int iTrade.NumTrades( htrade trade );

Parameters:
trade : The handle of the trade.

Return value:
Returns the number of offered trades.

See also:
 iTrade.NthTrade


iTrade.Offered

Get the name of the offered trade commodity.

prototype string iTrade.Offered( htrade trade );

Parameters:
trade : The handle of the trade.

Return value:
Returns the name of the offered commodity.

See also:
iTrade.NumOffers, iTrade.Faction, iTrade.Wanted


iTrade.Wanted

Get the name of the wanted trade commodity, category, or superset.

prototype string iTrade.Wanted( htrade trade );

Parameters:
trade : The handle of the trade.

Return value:
Returns the name of the wanted commodity, category, or superset.

See also:
iTrade.NumOffers, iTrade.Faction, iTrade.Offered


iTrade.JaffsTradeAdvice

Update Jafs' box with information about the trade.

prototype string iTrade.JaffsTradeAdvice( htrade trade );

Parameters:
trade : The handle of the trade.

Return value:
Information about the current trade.

See also:
iTrade.JaffsTradeDescription


iTrade.JaffsTradeDescription

Update Jafs' box with a description of the trade.

prototype string iTrade.JaffsTradeDescription( htrade trade );

Parameters:
trade : The handle of the trade.

Return value:
The description of the current trade.

See also:
iTrade.JafsTradeAdvice


Developing Scripts for I-War 2
This section deals with developing Pog scripts for I-War 2, and creating user mods.
  • Pog Compiler
  • Running Pog Scripts
  • Debugging Pog Scripts
  • File System
  • INI Files
  • CSV Text Files
  • Mod Creation
  • I-War 2 Header File Reference
Copyright (c) 1999-2002 Particle Systems Ltd. All rights reserved.


Pog Compiler

Overview

The Pog compiler compiles Pog scripts into Pog packages.

The compiler does not have a graphical interface - It is a win32 binary with a command line interface and is designed to be used with a programmers editor that allows you to define a code compilation program, or with DOS type batch files.

Pog File Types

The Pog compiler references the following file types:

.pog | A Pog script in PC text file format. See Pog Script Structure for details.
.pkg | A binary Pog package, created by the compiler when compiling a Pog script.
.h | A Pog header file for a Pog package, referenced by the compiler when compiling packages. Can also be created by the compiler from a Pog script during the compilation process. See Header Files for details.

Installing

The Pog compiler requires the following files and folders from the Pog SDK:

binaries folder - Contains the Pog compiler program and batch file.
include folder - Contains the Pog script header files.
samples folder - Contains sample Pog scripts for you to edit and compile.
compile.bat - Sample batch file for the compiler

To install the compiler:

  • Copy the contents of the binaries folder into the bin\release folder of your I-War 2 installation. Note: The compiler executable is called pc.exe
  • Copy the include folder a convenient location.
  • Create a folder to hold your Pog source files.
  • Create a resource\packages folder in your I-War 2 installation. This is where the game expects the packages to be installed. Note: Any packages placed here will override packages with the same name in the game's resource.zip file.
  • Place the compiler.bat file in a convenient folder.

Using the Compiler

We have included a DOS batch file with the Pog compiler - compile.bat that's already set up to compile Pog files. It assumes the following:

Game Folder | C:\Program Files\Infogrames\Independence War 2 - Edge of Chaos
Pog compiler location | <game folder>\bin\release\pc.exe
Header file location | c:\pog\include\
Package file destination | <game folder>\resource\packages\

To use compile.bat:

compile.bat <pog_script_name>

E.g.

compile.bat My_Script.pog

The package for the script name will automatically be placed in the package file destination folder. You can edit the batch file to change the location of the various folder locations.

Alternatively if you have a programmers editor you can set up the editor to use the Pog compiler directly using the Pog compiler options listed below and the compile.bat as a guide.

Pog Compiler Commands

The Pog compiler is a Win32 command line program. Here's the basic usage:

pc [options] file-name

Pog Script File Name

The Pog script file name must be specified at the end of the command line, and must include the .pog filename extension, e.g. My_Script.pog

Options

These options are not mandatory. If an option isn't specified, then its default value will be used. Options can be specified in any order.

General Options

--help or -h | Shows Pog compiler help information.
--quiet or -q | Quiet mode - do not display any messages.

Path Options

All paths are followed by a path parameter, and each path defaults to the current directory. Long filenames in the path parameters should be enclosed in double quotes "".

--include or -i | Search the specified folder for include files. (Multiple include paths may be specified with multiple -i parameters.)
--header-path or -hp | Place generated header files in the specified folder.
--assembler-path or -ap | Place generated assembler files in the specified folder. Note: This option has no use for Pog script development.
--package-path or -pp | Place generated package files in the specified folder.

Output Options

The default outputs are package and header files.

-make-package or -mp | Make a binary package file.
--make-header or -mh | Make a package header file.
--make-assembler or -ma | Make an assembler output file. Note: This option has no use for Pog script development.
--check-only or -co | Do not generate any files - just produce error and warning messages. This option overrides the other output options.
--no-debug or -nd | Do not generate code in debug statements - this option produces smaller, faster output files.


Running Pog Scripts

Getting a Pog script running in the game can be accomplished in several ways:

  • Modifying the scripts.ini file
  • Scenario mod function.
  • Using an existing game script.
  • Using the Test feature.

Modifying the Scripts.ini File

The scripts.ini file is located in the resource.zip. Whenever the game transitions from one major state to another (such as exiting from the player base into space) the scripts in the appropriate section of the scripts.ini are executed. Here's the default scripts.ini file:

[Game]
; Run these scripts atomically when the player starts a new game
enter[]=iStartSystem.StartupNewGame
enter[]=iFactionScript.Initialise

[Session]
; Run these scripts atomically when the player starts a new game
; or loads a saved game.
enter[]=iCargoScript.Initialise
enter[]=iStartSystem.StartupSession

; Run these scripts atomically when the player ends a game
exit[]

[Base]
; Run these scripts atomically when the player enters the base.
;enter[]=

; Run these scripts atomically when the player leaves the base.
;exit[]=

[Space]

; Run these scripts atomically when the player enters space.
enter[]=iStartSystem.StartupSpace
enter[]=iUtilities.AllowMissionSkipping
enter[]=iMissionTracker.Initialise
enter[]=iMusic.Initialise

; Run these scripts after the act scripts but before play begins
final_setup[]=iStartSystem.FinalSetup
final_setup[]=iBackToBase.Initialise

; Run these scripts atomically when the player leaves space.
exit[]=iStartSystem.ShutdownSpace
exit[]=iMusic.Terminate
exit[]=iBackToBase.Terminate

[System]
; Run these scripts atomically when the player enters a new system
enter[]=iStartSystem.StartupSystem
enter[]=iTrafficCreation.DisableTrafficReport
enter[]=iRangeCheck.DisableRangeReport
enter[]=iStation.DisableStationReactiveReport

; Run these scripts atomically when the player leaves a new system
exit[]=iStartSystem.ShutdownSystem

Only non-task functions with no parameters can be called using the scripts.ini file. The function used must be exported via the provides command in the script, and is specified without the parentheses, e.g. enter[]=iExample.MyFunction

See the INI File section for details of INI file creation and structure.

To modify the scripts.ini file it is best to extract it from the game's resource.zip file. You will need to create a resource folder in the game installation folder, and place the scripts.ini file in there. See File System for more information about zip files and the game's file system.

The advantage in using the scripts.ini file is that all the standard game scripts, such as space traffic creation, etc. will run alongside your script.

The disadvantage is that only one copy of the scripts.ini can be active at one time, so if two or more Mods that use the scripts.ini to run their scripts are active simultaneously, there will be a conflict and only one mod will work.

Scenario Mod Function

Versions of I-War 2 from F14.6 or later allow for user scenarios to be created. These user scenarios are accessed from the Extras screen.

Only one scenario can be active at any one time. The advantage to running a script via the scenario feature, is that it provides an easy user-friendly way to activate your script. The disadvantage is that none of the default game scripts (such as traffic creation) will run so if you want traffic, etc. you'll have to call the setup functions manually.

See Mod Creation and Distribution for more details.

Using an Existing Game Script

Another way of running your script is to piggy back your script on an existing script, by inserting the function call that starts your script into another one. However this requires you having the source code for the script you want to put your script initialisation call into.

Using the Script Test feature

Your can easily test a script by inserting a couple of entries into the game's flux.ini file. The advantage to this method is that it's very easy to get your script up and running. The disadvantage is that the script will replace the game's story script, and it requires you to manually edit the flux.ini file to get it working (which makes it not very useful if you intend to distribute your script).

To get a script running add these sections into the flux.ini file (Make a backup of the flux.ini first).

[Test]
package=iExample.MyScript
ship=ini:/sims/ships/player/comsec_prefitted

Replace the package entry with the call to your script function, and the ship entry with a prefitted player ship.

Important: The standard player ships will not work - you must use a prefitted ship with the necessary player systems already included.

Note: If your script uses states to restart itself automatically, then you may find your script runs twice if you enter then exit the player base. There are ways to get around this, e.g. by creating a global variable when your script first runs, then check for it in your script.


Debugging Pog Scripts

Overview

Pog does not feature a debugger, but it does include some features which help debugging Pog scripts. The most useful features are listed below.

Windowed Mode

When the game is running in full screen some pop-up debug messages will not appear. It's useful to run the game in windowed mode so that you can see these messages. It also allows you to easily switch between the game and any development software you may be using.

To set windowed mode you will need to change an option in the game's flux.ini file:

full_screen = 0

Set the full_screen option to 1 to run the game in a window, or back to 0 to run full screen.

Important: Don't set full screen mode if the game's screen size is set to a value bigger than your desktop.
Note: When running in window mode you can't change the game's screen size using the options menu. You must disable window mode first, or manually change the size by editing the flux.ini file.

Developer Mode

When active, Developer Mode shows debug information, such as the flux log and a frame rate counter. Additionally any statements in debug blocks are executed, providing additional debug information from those scripts that provide it.

Developer mode also activates various developer keys, providing you have a Control INI file with the developer key bindings.

Developer mode can be toggled on or of using the CTRL-ALT-D key (See debug control configs), or by changing the value of the developer_mode entry in the flux.ini file from 0 to 1. Make a backup of the flux.ini first!

Debug Control Configs

There are two control sets with debug keys included in the Pog SDK. These control configs are required if you wish to use any of the debug keys listed below.

They are located in the debug_configs folder. They replace the default.ini and keyboard_only.ini in the game's configs folder, so make a backup of original control configs first before you copy them over.

Debug Keys

SHIFT-G | Test a secondary mission.
CTRL-ALT-M | Multiplayer Debug
CTRL-F1 | Cycle all cameras
CTRL-ALT-D | Toggle developer mode
CTRL-ALT-Z | Toggle ship information mode. (Gives useful AI information)
CTRL-ALT-L | Reload modified resources. Note: May not work with release binaries.
CTRL-ALT-S | Toggle game statistics mode.
CTRL-ALT-T | Toggle Task viewing mode. Note: May not work with release binaries.
CTRL-ALT-P | Toggle Game profile mode
CTRL-ALT-B | Toggle Object Bounds - useful for viewing ship collision hulls and avoidance radiuses. Also shows location and orientation of ship's weapons and systems.
CTRL-ALT-R | Remote link to any ship.
CTRL-ALT-A | Show all contacts. Warning: Will create a huge contact list.
CTRL-ALT-TAB | Show player ship as a contact
CTRL-ALT-I | Make player Indestructable.
CTRL-ALT-X | Destroy current target. WARNING: USE WITH CAUTION. Don't use this to destroy indestructable ships or stations, or you could permanently destroy something the game's plot relies on, and prevent you progressing through the story.
CTRL-ALT-G | Jump instantly to the vicinity of the current target.
CTRL-ALT-K | Damage self
SHIFT-HOME | Toggle console (displays flux and pog log).
SHIFT-PAGEDOWN | Scroll console down.
SHIFT-PAGEUP | Scroll console up
SHIFT-END | Scroll to console end.

Flux Log

The game writes debug information to the flux.log file, which is located in the folder where the game is installed. How much information is shown in the flux.log depends on the debug settings in the game's flux.ini file.
Important: Make a backup of the flux.ini file before you make any changes to it.

Here are the flux.ini debug settings:

[Debug]
dev_call_tracing = 0
dev_memory = 0
dev_package_assert = 0
dev_package_trace = 0
dev_string_statistics = 0
developer_mode = 1
log_file = flux.log
trace_level = 3
trace_to_console = 1
trace_to_debugger = 0
trace_to_log = 1

The most useful options are:

developer_mode

Set this to 1 for the game to start off in developer mode, or 0 to start in normal mode.

trace_level

An integer number between 0 and 9. The higher the number the more flux debug information is displayed.
Note: Requires debug binaries for the higher debug levels.
Tip: Setting the debug level to 0 will display Pog script debug messages only - useful if you're debugging Pog scripts.

trace_to_console

Set this to 1 to output debug messages to the console (recommended).

trace_to_log

Set this to 1 to output debug messages to the flux.log (recommended).

The other options are mainly of use only with debug binaries, which are not supplied with the SDK.

Console

The console displays the content of the flux.log file, providing the debug setting trace_to_console is set to 1 in the flux.ini.

The console is by far the most useful debugging tool available, allowing you to view in-game the debug messages that are being written to the flux.log.

To make full use of the console your Pog scripts should output debug information using debug blocks and the Debug package.

Use of the console requires developer mode, and the debug control configs.

The console is turned on and manipulated with these debug keys:

SHIFT-HOME | Toggle console on / off
SHIFT-PAGEDOWN | Scroll console down.
SHIFT-PAGEUP | Scroll console up
SHIFT-END | Scroll to console end.


File System

Overview

I-War 2 features a flexible file system that can read both normal files and folders, and zip files.

A zip file is an archive designed for easy distribution of files and folders. Zip files support compression, to reduce the zip file size. Zip files have the file extension .zip, e.g. file.zip. You can create, modify and read zip files using programs such as WinZip.

The game treats zip files and folders identically - a zip file called my_files.zip would be considered to be the same as a folder with the same content called my_files.

Note: The game uses files in folders in preference to zip files. Thus if a folder and a zip file are in the same location and share the same name, then the files in the folder will be used over the files in the zip. This feature is very useful as you can 'override' files in a zip with modified version by placing them in an indentically named folder (omitting the .zip extension).

Game Resources

The majority of the game's resources, such as graphics, ship definitions, etc. are held in a zip file in the game's folder called resource.zip. Additional resources for localised versions are held in a supplemental zip file such as resource_french.zip. Another folder called streams contains video and audio files.

The game's flux.ini file defines which folders / zip files are searched for resources, and in which order.

The flux.ini section [FcResourceManager] contains at least these two entries:

search_paths[0] = .\resource
search_paths[1] = .\streams

These are standard INI File numbered entries, each of which defines a folder / zip file to search for game files. The path names are all relative to the game's install folder. In the example above the game would search for a file in this order:

  1. In a folder called resource.
  2. In a zip file called resource.zip.
  3. In a folder called streams.
  4. In a zip file called streams.zip.

Only if the game failed to find the file in all the resource locations would it fail with an error.

You can add your own paths to the flux.ini if you wish, but make a backup of the flux.ini first. See the INI Files section for information on numbered INI file entries.

However, the game features an automatic system where you turn new resources on and off. See the Creating and Distributing Mods section for details.


INI Files

Overview

Initialisation files, known as INI files are text files used extensively to configure various elements of the game, such as spaceships, game options, etc.

INI files have the extension .ini, and are referenced with the ini: request in Pog resource request URLs, e.g.:

ini:/sims/ships/player/comsec_prefitted

INI files are controlled in POG by the INIFile package.

Important INI Files

Here are the most important INI files in the game. Other INI files such as the ship and weapon INI files are too numerous to be listed here.

Note that most of these files are inside the resource.zip. See File System for more information.

Important: Before modifying an INI file make a backup first!

flux.ini | \ | The main configuration file for the game.
planets.ini | \resource | Defines planet textures and colours.
scripts.ini | \resource | Defines the scripts that activate when the game's mode changes.
ship_names.ini | \resource | Defines the numbers of ship names available for each Faction
station_creation.ini | \resource | Defines the station ini files used for each station type

INI File Structure

INI files are PC format text files. They consist of headed sections that contain numbered lists of entries. These entries can be read by Pog scripts using the INIFile package.

Here is an example ini file

[Example1]
example_name = "my example"
example_number = 1

[AnotherExample]
example[0] = 0.3
example[1] = 0.2

Section Header

INI Files contain sections of entries. Each section is defined by a section header. Section header names are enclosed in square brackets, and the names are case sensitive. By convention an INI File section headers use upper and lower case, and have no spaces between words e.g.:

[ExampleHeader]

INI files must have least one section header.

Section Entries

Each section of an ini file can contain zero or more named entries. Entries consist of a name followed by an equals sign, followed by a value. By convention the entry names are lower case and use underscores as spaces between words, e.g.:

example_entry = 1

Entries can be one of four types:

Integer
An integer number e.g.

example_integer = 1

Float
An floating point number e.g.

example_float = 0.9

String
A string of characters.

example_string = Characters

Note that if the character string encloses spaces it must be enclosed with double quotes "", e.g.

example_string = "More characters"

Vector
A vector entry is a set of x, y and z values (in that order), enclosed by parentheses and separated by commas, e.g:

example_vector = (20,90,100)

Note:
The type is not specified in the INI file entry, thus it is important to know exactly what type an entry represents before you attempt to read it using your Pog script.

Also note that an entry is not required to have a value, as the Pog INIFile package allows you to specify a default value if an entry does not exist, or does not supply a value.

Numbered Entries

Multiple entries with the same name can be created using the numbered entry system. This system allows you to iterate in Pog through a list of identically named entries.

Numbered entries are defined by a number enclosed by square brackets following the name, e.g.

[Example List]
example_numbered_entry[0] = 1
example_numbered_entry[1] = 9
example_numbered_entry[2] = 5

Any entry type can be numbered.

It is important that the number sequence begins with zero and all the numbers are sequential. A gap in the sequence will be interpereted by Pog scripts as the sequence end, and any entries after a sequence gap will not be read.

In some circumstances with some INI files it's possible to omit the numbers, with the game automatically picking up all entries in a sequence. The scripts.ini file behaves in this way. Unfortunately the Pog script INIFile package does not support this feature.

Here's an example of a number sequence with the numbers omitted:

entry[] = 2
entry[] = 3
entry[] = 0

Comments

You can put single line comments into an INI file using the semicolon character ; e.g.

; This is a comment.

The semicolon must be at the beginning of the line.


CSV Text files

Overview

Flux supports a text localisation scheme. Text in the game is defined by text keys which are automatically replaced by localised text in the appropriate language. The game's text and their keys are held in comma separated database files (CSV Files). These files are separate from the game code and easily edited. Differerent languages can be easily implemented by replacing the CSV files with localised versions.

CSV files have the extension .csv, and are referenced with the csv: request in Pog resource request URLs, e.g.:

csv:/text/mytext

CSV files are controlled in Pog by the Text package.

CSV Format

The CSV file format is very simple, and consists of text separated by commas and newlines. It can be read by most spreadsheet and database programs. It is best to use a text editor, as other programs can add extraneous information to the files when editing that can cause problems in the game.

Each line in a CSV consists of either a comment, or a CSV text entry.

Comments

You can put single line comments into an CSV file using the semicolon character ; e.g.

; This is a comment.

The semicolon must be at the beginning of the line.

CSV Text Entry

A CSV text entry consists of two parts, a text key, and localised text, separated by a comma and ending in a new line. e.g:

text_key, "Localised text"

Text Key
The text key is the text that Pog scripts use in their various commands. By convention text keys use lower case with underscores for spaces. Each text key must be unique, so a good practice is to make the text key representative of the localised text content, and to include a prefix for text associated with a particular script and purpose, e.g:

mission_01_dialogue_clay_we_are_in_trouble
mission_01_text_time_remaining

Note: The game's dialogue system uses the text key as the name of the sound file to play, i.e. a text key called my_dialogue would reference a sample called my_dialogue.wav.

Localised Text
Localised text is the text that's displayed on-screen (providing your Pog script has the correct text key!). If the text contains a comma it must be enclosed by double quotes "". It is good practice to enclose all localised text in double quotes, e.g:

"Localised text, this line includes a comma."


Creating and Disributing Mods

Overview

A Mod is a user modification for a game, changing or adding to the game's functionality. To simplify distribution of Mods versions of I-War 2 from 14.6 includes special support for mod zip files.

If you require the F14.6 patch, then please visit the Independence War Website.

Mod Zip Files

A mod zip file is a zip archive containing all the files required for a user mod. The mod file uses the same folder structure as the game's standard resources, and when active any files in the mod zip will override identically named files in the game's resources.

See File System for an overview of the game's file system, and its use of zip files.

Mod zip files are placed in the game's mods folder. The game will automatically detect any mods located there and make them available for activation on the Extras screen. This makes it easy to distribute your mod, as your mod is a single file, and no special knowledge is needed to install it.

User Mod Types

There are two types of Mods, mods and scenarios. Mods modify a part of the game, and can be turned on and off. More than one mod can be active at the same time, providing they don't attempt to modify the same resources. Scenarios are self-contained missions or scenarios, and only one can be active at a time.

Note: Mods that contain Pog packages cannot be turned off properly once they have been turned on in the game, as the packages can't unload once they are in-use. If you turn off a Mod containing a Pog package you must exit the game and restart it to register the change.

Putting Together a Mod

Create a folder for your mod. Name it so that it reflects the mod's name, e.g. location_finder, or manual_countermeasures.

Put all the files for your mod in the folder, keeping the same folder structure as the original files.

Use a zip program such as WinZip to turn your folder into a zip file. Make sure that the folder names in your mod are included in the zip file. Also make sure that the folder name of your mod is NOT part of the path name of the files in the mod.

You can optionally create two additional files in that inform the game about the content of your mod. These should be placed in the root folder of the mod zip file.

Mod INI File
This is a small INI File that informs the game of the name of your mod. By default the game uses the name of your mod zip when it shows a list of available mods, but if you prefer to have a properly formatted name you can create a mod INI file.

The INI filename should be the same filename as your mod, i.e. for a mod called my_mod.zip use the filename my_mod.ini.

The contents of a typical mod INI file looks like this:

[Info]
display_name = "Location Finder"

Just change the name to the name of your mod.

Mod HTML Readme
This is a HTML text file that scrolls up the screen when your mod file is selected. The version of HTML used in the game is limited and supports only basic features such as horizontal rules, and bold and italic text.

The HTML filename should be the same filename as your mod, i.e. for a mod called my_mod.zip use the filename my_mod.html.

Scenarios

Scenarios are a special form of mod. You put them together in exactly the same way as normal mods, but scenarios require a Pog package containing the Pog script for the mod. (You can have more than one package, but you must have at least one package.)

The package filename should be the same filename as your mod, i.e. for a mod called my_mod.zip use the package filename of my_mod.pkg. The package must be in a packages folder in the zip (just as in the resource.zip)

In addition the Scenario package should contain a function called ScenarioMain() This function is called when you select the scenario on the extras screen.

When a scenario is called, the game is still in the front end or GUI. This allows you to make GUI screens that display before your scenario properly starts, for example a ship selection screen, or a high score table. To get the scenario to enter space you will need to use these lines of code:

iGame.SetGameType( IGT_Mod );
iGame.StartNewGame( "map:/geog/badlands/hoffers_wake", "challenge_course" );

The first line specifies that a MOD game type is running.

The second specifies the starting map to use for the mod, and the package to use. The game will then call the function Main() in your scenario package when the space screen has loaded. Just replace the example map and package with the map and package required for your own mod.

Distributing Mods

You are free to distribute your mod in accordance with the Mods License ageement.


Pog Header Reference

Header File Reference

Overview

This section lists the header files supplied with the Pog SDK. Most of the headers represent packages supplied with I-War 2, others represent enumerations of specific data used in the game.

This page is split into several sections for easy reference.

  • Flux native code
  • I-War 2 native code
  • I-War 2 scripted functionality
  • I-War 2 scripted debug
  • I-War 2 scripted story and missions
  • I-War 2 scripted multiplayer

If a header file has a hyperlink, you may click on it to view full documentation for the header file's package. Otherwise please refer to the header file itself, which will contain a full listing of commands available in the header's corresponding package.

Flux native code Package Headers

These headers represent Flux native code packages.

Header File | Purpose
CDAudio.h | Controls CD Audio playback.
Config.h | Game configuration settings manipulation.
Debug.h | Debug message printing.
Global.h | Global variable support.
Group.h | Sim grouping functionality.
GUI.h | GUI construction and manipulation.
INIFile.h | INI File manipulation.
Input.h | Control input binding.
List.h | List data structure handling.
Lock.h | Game locking functionality.
Math.h | Mathematical function library
Object.h | Object Property manipulation.
Set.h | Set datatype manipulation.
Sim.h | Sim creation and manipulation.
State.h | State creation and manipulation.
stream.h | Audio stream playback.
String.h | Text string datatype manipulation.
Subsim.h | Subsim creation and manipulation.
Task.h | Task creation and manipulation.
Text.h | Localised text manipulation.

I-War 2 native code Package Headers

These headers represent I-War 2 native code packages, and their enumerations.

Header File | Purpose
iAI.h | Artificial Intelligence commands.
iBody.h | Finding and manipulation of bodies in a solar system.
iCargo.h | Manipulation of cargo and cargo types.
iComms.h | Communications and dialogue system commands.
iDirector.h | Real-time cut-scene commands.
iDockport.h | Docking port manipulation.
iEmail.h | Email manipulation.
iFaction.h | Faction creation and manipulation.
igame.h | Special game utility functions.
iHabitat.h | Space station finding and manipulation commands.
iHUD.h | Head Up Display manipulation commands.
iInventory.h | Manipulation of the inventory.
iLagrangePoint.h | Finding and manipulation of Lagrange points.
iLoadout.h | Player ship Loadout manipulation.
iMapEntity.h | Finding and manipulation of map entities.
iMod.h | Querying and configuring mods.
iMultiplay.h | Multiplayer commands and functionality.
iObjectives.h | Creation and manipulation of in-game objectives.
ioptions.h | Creating, saving and manipulation of game configuration data.
iRegion.h | Creation and manipulation of space regions, such a traffic control regions.
iRemotePilot.h | Remote piloting functionality.
iScore.h | Manipulation of the game's scoring system.
iShip.h | Creation and manipulation of spaceship sims.
iSim.h | Creation and manipulation of I-War 2 sims.
iTrade.h | Creation and manipulation of trades.
MapEnumerations.h | Enumerations for the various map objects

I-War 2 Scripted Functionality

These header files represent packages that have been scripted specially for I-War 2 in Pog. Some are general purpose, others more specialised for the game.

Header File | Purpose
ABB_Common.h | Scripted utilities.
CargoTypes.h | Enumeration of all cargo types in the game.
iBackToBase.h | Utilities for the instant back to base feature.
iBaseGUI.h | User interface scripts for the player base.
iCargoScript.h | Cargo types initialisation script.
iCleanup.h | Utilites for mission re-start (obsolete).
iConversation.h | Scripted conversation utilities.
iCutsceneUtilities.h | Real-time cut-scene utilities.
iDeathScript.h | Scripted death scripts and utilities.
iEscort.h | Scripted Escort formations.
iFactionScript.h | Faction initialisation script.
iFight.h | Scripted functions for AI reactive fight.
iFlee.h | Scripted functions for AI reactive flee.
iFormation.h | Scripted ship formations.
iFrontendGUI.h | GUI scripts for the front end menus.
iGUI.h | Scripted GUI utilities.
iIgnore.h | Scripted functions for AI reactive ignore.
iJafsScript.h | Scriped Jafs behaviour and utilities.
iMusic.h | Scripted music playback.
iPDAGUI.h | GUI scripts for the in-game menu.
iPilotSetup.h | Scripted pre-set AI pilots.
iRangeCheck.h | Traffic creation range checking utilities.
iScriptedOrders.h | Traffic scripted behaviours.
iShipCreation.h | Ship creation utilities.
iStartSystem.h | Scripts and utilities for setting up and shutting down space-flight.
iStation.h | Station reactive scripts.
iTrafficCreation.h | Traffic creation utilities.
iTrafficScenario.h | Traffic scenario utilities.
iUtilities.h | Miscellaneous script utilities.
iWingmen.h | Wingmen and turret fighter manipulation.

I-War 2 Scripted Debug

The packages these headers represent are designed specifically for debugging I-War 2's functionality, story and dialogue.

Header File | Purpose
actonecsvs.h | Scripted utilities to check the act one dialogue and text.
actthreecsvs.h | Scripted utilities to check the act three dialogue and text.
acttwocsvs.h | Scripted utilities to check the act two dialogue and text.
actzerocsvs.h | Scripted utilities to check the prelude dialogue and text.
csvchecker.h | Scripted utility to check dialogue and text.
empty.h | Empty package for testing purposes
ipowerup.h | Scripted utilities to add cargo, player ships ,and player weapons.
misccsvs.h | Scripted utilities to check miscellaneous dialogue and text.

I-War 2 Scripted Story and Missions

The packages these headers represent comprise the game's story and mission content.

Warning! Contains spoilers.

Header File | Purpose
iAct0GeneralTraining.h | Training for the prelude.
iAct0Mission10.h | Home Sweet Home mission.
iAct0Mission20.h | Proving Grounds mission.
iAct0Mission40.h | Errand Boy Mission.
iAct0Mission50.h | Junkyard Challenge mission.
iAct0Mission60.h | Nemesis mission.
iAct0MissionTour.h | Grand Tour mission.
iAct1Mission01.h | The Great Escape mission.
iAct1Mission02.h | The Stepsons mission.
iAct1Mission03.h | Joint Forces mission.
iAct1Mission04.h | The Heist mission.
iAct1Mission05.h | Marauder Cache mission.
iAct1Mission06.h | The Trouble With Gunstars.
iAct1Mission07.h | Showdown mission.
iAct1Mission08.h | League Initiation mission.
iAct1Mission09.h | Construction Yard mission.
iAct1Mission10.h | Lucrecia's Hoard mission.
iAct1PiracySpecial.h | Candy From A Baby mission.
iAct1WingmenTraining.h | Wingmen training.
iAct2Mission01.h | Picking Up The Pieces mission.
iAct2Mission02.h | Meet The Oman mission.
iAct2Mission03.h | Trouble At The Ranch mission.
iAct2Mission04.h | High Noon mission.
iAct2Mission05.h | Blockade Runner mission.
iAct2Mission07.h | The Exile mission.
iAct2Mission08.h | Corporate Holdings mission.
iAct2Mission10.h | Grassy Knoll mission.
iAct2Mission11.h | Unification mission.
iAct2Mission13.h | The Kong Fracture mission.
iAct2Mission18.h | Momma Wolf mission.
iAct2Mission20.h | Battle of Mwari mission.
iAct2Mission22.h | Wolf's Lair mission.
iAct2Mission24.h | Hide and Seek mission.
iAct2Mission25.h | Dante's Inferno mission.
iAct3Mission01.h | Corporates On The Run mission.
iAct3Mission02.h | Clash Of The Titans mission.
iAct3Mission03.h | Scavenger mission.
iAct3Mission04.h | Bridgehead mission.
iAct3Mission05.h | Deep Cover mission.
iAct3Mission06.h | Smokescreen mission.
iAct3Mission08.h | Get Hoffer mission.
iAct3Mission09.h | Raising the Ante mission.
iAct3Mission10.h | Into Chaos mission.
iActOne.h | Act one story script.
iActThree.h | Act three story script.
iActTwo.h | Act two story script.
iExodusTraffic.h | Act three special traffic scripts.
iGangsterIncidentGen.h | Marauder encounter scripts.
iGMTemplates.h | Generic (secondary) Mission template scripts.
iGMTracker.h | Generic Mission tracker scripts.
iMissionGenerator.h | Generic mission Generator.
iMissionGeneratorSelector.h | Generic mission selector.
iMissionTracker.h | Mission tracking utilities.
iPrelude.h | Prelude (act zero) scripts.
iSystemCutScene.h | Cuts-cenes showing each solarsystem.
iInstantAction.h | Instant action script.

I-War 2 Scripted Multiplayer

The following headers represent scripted Pog packages for multiplayer functionality and scenarios.

Header File | Purpose
iBombTag.h | Bombtag scripted multiplayer scenario
iBotPak.h | Scripted AI bots for multiplayer
iMap.h | Multiplayer map loading and manipulation.
iMPUtils.h | Scripted multiplayer utilities.
iMultiplayGUI.h | Multiplayer GUI scripts.
iNetworkGUI.h | Network GUI scripts.
SimpleFlagCapture.h | Capture the flag scenario.
SimpleFragFest.h | Deathmatch scenario.